Documentation writing style guide

[provinzkraut]

Currently open questions:

1. Capitalization of headlines (Proper capitalization, titlecase, etc.)
2. Grammatical mood (we enforce imperative mood in docstrings, prose docs currently vary)
3. Addressing the reader directly (currently varies, although reader is addressed directly most of the time)

[provinzkraut]

My opinions:

1. We should follow proper capitalization. It's proper and in my personal opinion causes less confusion about terminology since it's easier to make out proper nouns and such
2. I slightly prefer imperative mood, but we currently mainly use a mix of subjunctive and indicative. I'm not sure if there's a benefit to enforcing a specific mood here. Maybe for distinct sections (e.g. tutorials should not use imperative, technical background explanations should use indicative), but overall this doesn't feel very important. As long as the moods don't vary wildly within a paragraph or chapter, most readers probably won't even notice
3. We currently address the reader directly most of the time, and I think we should keep it at that. It's the most common style in other documentations as well, and people are used to it. Unless anyone has good reasons not to, I'd say let's do that.

[Jarmos-san]

Continuing from this comment here's what I've to say to about following a standard style guide for the documentations:

1. Each first letters of the words in a headline should be capitalised. A good reference for such a justification can be found in this article - What Words Should be Capitalised in a Headline?. But to be honest, I'm merely being nitpicky here & following a standard practice across the entirety of the docs is what we should be striving for instead.

2. Certain sections of the documentations (like the reference material, tutorial & such) can be written in an imperative mood. But I don't think there's a silver bullet for this context & instead we can make use of Vale to enforce an uniform writing standard for the docs.

3. The tutorial & how-to guides section of the docs should address the reader directly. Those section of the docs exists for the highest user engagement after all. The remaining reference materials & such can make do by not addressing the user at all though.

[provinzkraut]

But to be honest, I'm merely being nitpicky here & following a standard practice across the entirety of the docs is what we should be striving for instead.

I agree, I guess that's mostly what I was going for with this. It's more important that it's consistent than what it actually is.

Vale looks interesting, haven't heard of that before. Would you want to set this up for us to experiment with?

[Jarmos-san]

Would you want to set this up for us to experiment with

Sure! I guess having vale setup properly will benefit restructuring the prose & the "usage guidelines" section (as discussed on Discord) as well. I'll send a PR with the necessary tools & pre-commit hooks in a couple of days.

[JacobCoffee]

I have no hard-line opinion on the documentation style; it is only some kind of style that I've seen that is appealing.
Also on point 1 if we go with this style I think each major word should be capitalized but 'minor' words such as "the", "of, "in", "a", "if", etc. should not be... e.g.
Contribution Style Guidelines
Examples for Contributors
Read the Docs

[Jarmos-san]

On that note, I'm experimenting with vale right now & it appears I can download specific prose style guides established by the likes of Microsoft & Google. And they suggest sticking with sentence-case for headings.

Any way let's see how do things turn out with Vale when #1093 is complete.

[provinzkraut]

specific prose style guides established by the likes of Microsoft & Google

That's what was intriguing to me; The fact that you can use already-established styles of people who have put way more thought and research into these questions than us. I'd say we should adopt one of those styles, so we won't need to have discussions about details like this. it's like using black for code formatting. I might not agree with all the stylistic choices it makes, but it's one less decision to be made and one less thing to argue about.

[Jarmos-san]

Yeah exactly, I chose to go with Google & I believe its possible to change to some other guide (if necessary). Some stylistic choices doesn't make sense to me either. For example, Google suggests not over using parentheses but Vale can be configured to ignore those choices as well!

Here's an example:

; In the .vale.ini file
[*.{md,rst}]
Google.Parans = No