Consider using a style guide for writing

[StevenMaude]

Use of style guides might make the documentation more consistent.

[StevenMaude]

Ideas

There are at least two distinct aspects here to consider.

Content style guide

How we should write the content.

This might be enforced somewhat via linting, if there's a suitable linter; for example, using Vale.

If we choose to do this, we should probably choose an existing style guide and extend it with any extra rules we require.

Examples

Included as examples here only, not necessarily what we should do ultimately:

• Use British English spelling.
• Write "OpenSAFELY" when referring to the platform. You may use opensafely when referring to other aspects such as the opensafely-cli or our GitHub organisation.
• Reuse nouns where the use of a pronoun might be confusing.
• Use bulleted lists where you're specify a list of items.

Markup style guide

How we should write the Markdown (examples: formatting of numbered lists).

This, too, might be enforced somewhat via linting, if there's a suitable linter (examples: markdownlint, or another markdownlint).

It's possibly easier to enforce, as we're only interested in the Markdown syntax and structure here. That said:

• I don't know how configurable any existing linter is
• Material for MkDocs has lots of custom features that might not be covered by existing linters

Examples

Included as examples here only, not specifically necessarily what we should do ultimately:

• Use semantic linebreaks for new content. Amend old content you are editing to use semantic linebreaks.
• Use the "atx" # heading format, not the "setext" =====, ----- format.
• Use * for bulleted lists.

Crossover

Some items may actually crossover to some extent. Sometimes the available features in Markdown may influence how you write content.

Examples

• Use of admonitions; these dictate both how you write your content ("it's preferable to not write 'beware', but use a danger/warning admonition instead)
• Favour the Material for MkDocs data tables feature for content that would suit a table over representing tables via a screenshot or a big list of entries.

[StevenMaude]

This really crosses over with #643, which is about providing tooling for editors and applying rules to pull requests.

[StevenMaude]

Actual example use case: we want to use "SNOMED CT" throughout text; #909.