Style guide

[mark-wiemer]

Aside from the technicalities of how to contribute, we should clarify the style of the docs site. For example, do we use Sentence case headings or Title Case Headings? This will be an iterative process, but it's something we should start early to get the docs looking professional and helping folks navigate the site and lower cognitive load.

[appgurueu]

I don't think it matters much, the style is consistent enough currently I think (e.g. sentence case is pretty prevalent for titles, # is used for headings, * for list items).

Note also that having to follow style guides - assuming they wouldn't be automatically applied - increases the cognitive load for editors and reviewers.

[mark-wiemer]

The adage goes "docs are read 100x more than they're written", I'm OK with a bit of cognitive load on doc writers, and I do think we can automatically enforce a good chunk of any style guide :)

Also note that most headings are currently Title Case, not sentence case, at least from what I've seen. Not a big deal to me but important to clarify in this discussion

[JosiahWI]

Any style guides we have need to be enforced in CI where possible.

[mark-wiemer]

Happy to close this one in favor of iterative discussions as things come up