Document a brief style guide

[duncandewhurst]

Topics:

• Decide on British or US English and use it consistently #19
• Use of active voice

Can review the BODS and OCDS style guides for inspiration

• https://openownership.github.io/bods-dev-handbook/style_guide.html
• https://ocds-standard-development-handbook.readthedocs.io/en/latest/meta/index.html

Location: https://os4d.opendataservices.coop/meta/

[kathryn-ods]

I think the general style guide points are

• use British English spellings (e.g. "organise" not "organize")
• use the active voice not the passive voice (e.g. "give feedback too..." not "feedback needs to be given to..."
• aim for a Hemingway readability score of grade 8

@duncandewhurst couple of questions

We could be more consistent in making sure acronyms are defined on every page where they are used (e.g. IATI in https://os4d.opendataservices.coop/components/publication_statistics_dashboard/) but if this is primarily for internal use maybe that's overkill?

Specific terminology

• what is the difference between adopters and implementers? Is this clearly defined or are these terms being used interchangeably?
• in the patterns section we have headings for "solution" and "method." Could these be combined under "solution" or is it important to disambiguate the abstract from the practical?

[duncandewhurst]

The general points sound good.

We could be more consistent in making sure acronyms are defined on every page where they are used (e.g. IATI in https://os4d.opendataservices.coop/components/publication_statistics_dashboard/) but if this is primarily for internal use maybe that's overkill?

Since much of the documentation isn't expected to be read end-to-end, I think it makes sense to expand the first use of acronyms on each page.

Specific terminology

* what is the difference between adopters and implementers? Is this clearly defined or are these terms being used interchangeably?

I think they're presently used interchangeably, but adoption and implementation do mean different things so I think that we should use them correctly and consistently. I've proposed definitions in #46. For now the style guide could link to that issue, and once it is closed we can link to the definitions in the documentation.

* in the patterns section we have headings for "solution" and "method." Could these be combined under "solution" or is it important to disambiguate the abstract from the practical?

I think that we could combine them. In #46, I suggested "recommended approach", but "solution" is probably more in keeping with the pattern paradigm.