docs: 📝 add configuration guide

[joelostblom]

Description

Closes #21

Needs athorough review.

Checklist

• Formatted Markdown (with rumdl... 😮 )
• Ran just run-all

[lwjohnst86]

Nice start! I think it will need a bit of a revise to make it more of a how-to and less of a reference. Most of this reference information is in the docstrings of the functions/classes themselves.

[lwjohnst86]

Rather than list all the options here (which will quickly drift when things are actually implemented), refer instead to the help docs of build or view (or maybe even Config.

[lwjohnst86]

This reads a bit too much like a reference doc than a how-to. Could you revise it generally to be more instructional?

[joelostblom]

I believe the beginning is already written in an instructional (or at least more narrative) style. Commit ef858b5 includes a few updates to make the section "The configuration file" and onward sound more instructional. However, there isn't that much to "instruct" the reader to do since the effect of changing these options to different values is described elsewhere in the docs. The few things for the reader to learn from this page seems to be where Flower reads configuration from and which options can be entered into these files (but not what happens when those option values change).

[lwjohnst86]

There's parts of the guide that are more declarative/command-tense than instructional, e.g. in line 34-35 or paragraph in line 92-95. They don't require major changes to make them more instructional, just a few words/sentence to change the tone/tense. For example, see my suggested change in line 95.

[joelostblom]

I accepted your change in 95. I'm unsure how to rewrite 34-35; the current phrasing is from your previous suggestion in dfff2de.

[lwjohnst86]

@joelostblom don't forget to move the item back into review when you're done making changes, otherwise we don't know if you want us to review it or not (when browsing the board).

[lwjohnst86]

There's parts of the guide that are more declarative/command-tense than instructional, e.g. in line 34-35 or paragraph in line 92-95. They don't require major changes to make them more instructional, just a few words/sentence to change the tone/tense. For example, see my suggested change in line 95.

[joelostblom]

don't forget to move the item back into review when you're done making changes, otherwise we don't know if you want us to review it or not (when browsing the board).

Sorry, I keep thinking that this is automatic when clicking "re-request review", but I see that there isn't an available workflow action to trigger on that event.

[joelostblom]

I accepted your change in 95. I'm unsure how to rewrite 34-35; the current phrasing is from your previous suggestion in dfff2de.

[K-Beicher]

Don't know if you need a formal approval from me, but here it is.