Docs: Adopt a style guide

[astrojuanlu]

Historically we haven't had a great style guide. Definitely somewhere to improve! :)

Originally posted by @ericholscher in #8082 (comment)

This came after a question about whether to capitalize the first word of each list item. There are surely many other points where we are not being completely consistent.

We have a tiny number of recommendations in our docs, but they are clearly insufficient.

Rather than writing our own style guide, we could adopt an already existing one. For example, the Write the Docs community has some material on style guides.

In particular, the GNOME Documentation Style Guide covers how to capitalize and punctuate list items. I chose it on the basis of affinity, but there are many others. I don't really have any technical reasons to pick one or another.

Thoughts?

[humitos]

I don't have too much to say about what style guide to adopt, but I want to mention some points:

• the less rules the better
• the simpler rules the better
• the easier to remember the better
• the more automated/enforced via a linter the better (see Setup vale linter bot #5876)

[astrojuanlu]

I didn't know about https://docs.errata.ai/vale/, interesting! I see there was an attempt to add it to our repository but it stalled. We can continue the discussion about it in #5876, and keep this broader one open.

[ericholscher]

If I had to randomly pick one, I'd probably choose this one: https://content-guide.18f.gov/ -- I think it's a good general approach and higher level and rule-based approaches, but not too heavy IMO.

[agjohnson]

I'm +1 on a style guide if it seems like it would help to have some rules to fall back on. The GNOME style guide covers a few areas I would say our contributions usually have issues, but this guide is a lot to digest. A simpler guide would perhaps be a better fit for our team, especially where we aren't technical writers or dedicated to technical writing.

I think this question mostly comes back to enforcement for me. Most of our doc contributions have been by team that is not english first language, and so formal english technical writing is already a significant hurdle to writing documentation. While enforcement of a style guide might be a burden for team not used to writing formal english, we could at least have a common goal for our documentation or those used to formal, technical english writing.

I do think we need some list of rules that team can follow. That could be a very short list of areas that we usually have trouble with -- a list of terms at very least, and other area we commonly have trouble with in docs. But perhaps a style guide is more of a suggestion that a requirement for now?

I'm generally -1 on solving this problem with code. Language and communication is a tough problem even for humans to solve.

[humitos]

I agree with Anthony here!

I'm generally -1 on solving this problem with code. Language and communication is a tough problem even for humans to solve.

My point about using code here is to validate minor style consistency over all the documentation, not about the how it's written: tone, sentences, active/passive voice, etc. Some minor rules that we can automate:

• use Read the Docs, instead of RTD, or RTfD, or RTFD or ReadTheDocs, etc
• use "Read the Docs for Business" instead of commercial, etc
• always capitalize numbered/unsorted list
• etc

I think that "some of the rules" that we get from the Style Guide can be written in code and enforced, but there will be a lot of them that won't and that's fine.

[agjohnson]

Gotcha. Yeah, that stuff is a lot easier to catch with automated tooling. Vale can catch both and I've never been impressed with the value rule sets for tone/clarity etc. In the end, vale is a pile of regex searches and this lends well to simple rules like this perhaps.

[Daltz333]

https://github.com/wpilibsuite/ohnoyoudidnt is an opinionated style checker with doc8 that the WPILib team is developing for our docs.

[ericholscher]

Of interest: https://docs.google.com/document/d/1HxtaiayAJZvF0ZfNjLvRH3vYMvGTEki_TK8hFilQNJ0/edit#heading=h.7iuzbi54y1el -- style guide template

Also: https://github.com/thegooddocsproject/incubator/tree/master/style-guide

[astrojuanlu]

Some nice words about vale https://passo.uno/posts/first-steps-with-the-vale-prose-linter/

(@ericholscher points out that it's used on Write the Docs https://github.com/writethedocs/www/blob/master/vale/WTD/Branding.yml, https://www.writethedocs.org/guide/tools/testing/?highlight=linting#style-guide-checking-and-linting)

[astrojuanlu]

Beyond the discussion on whether to automate some rules or not, while working on #8528 I was thinking that a distinct language should be used for instructional documentation and design documents. Case in point: https://docs.readthedocs.io/en/stable/development/design/theme-context.html is a design document, but reads as a tutorial:

Before calling sphinx-build to render your docs
...In case you want to access to this data from your theme

I don't know if there are precedents for this, but while tutorials are written in second person, I think design documents should abstain from it, and instead refer to "the user", "the reader", and such.

[astrojuanlu]

Another thing mentioned in #8528 (comment): consistent characters for headings. Most of our pages do:

1. ===
2. ---
3. ~~~
4. ? possibly +++

[humitos]

I was thinking that a distinct language should be used for instructional documentation and design documents

I don't think we should enforce too many things for design docs since they are only used internally to share knowledge and discuss a potential idea. They are not thought to be shared with users --in fact, we have talked about removing them from our documentation.

[humitos]

We have created a style guide at https://dev.readthedocs.io/en/stable/style-guide.html