7.11 Spelling, Grammar, and Style [Dido Solutions, Inc Wiki]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== 7.11 Spelling, Grammar, and Style ======

[[fxdemo:05-part:start | Go To Top ]]

[[fxdemo:05-part:07-naming-and-file-conventions:start | Return to Naming and File Conventions ]]

The team should write [[dido:99_annexes:annex-b-terms-and-definitions:r:repository|Repository]] documentation, comments, file headers, script help text, [[dido:99_annexes:annex-b-terms-and-definitions:c:configuration|Configuration]] descriptions, generated documentation templates, catalogue entries, and acceptance [[dido:99_annexes:annex-b-terms-and-definitions:e:evidence|Evidence]] in clear, consistent English.

Project documentation should use UK spelling unless a tool, programming language, external standard, product name, API, command, package, or quoted source requires another spelling. Examples include “artefact”, “behaviour”, “organisation”, “normalise”, “initialise”, “modelling”, and “authorisation”.

The team should use active voice where practical. Documentation should identify the actor responsible for an action, such as “the script validates prerequisites” or “the [[dido:99_annexes:annex-b-terms-and-definitions:n:node|Node]] publishes status”, rather than relying on passive constructions such as “prerequisites are validated” or “status is published”.

The team should use consistent terminology from the architecture documents and the handbook. Terms such as Node, Topic, [[dido:99_annexes:annex-b-terms-and-definitions:d:data_structure_definition|Data Structure Definition]], [[dido:99_annexes:annex-b-terms-and-definitions:d:data_structure_instance|Data Structure Instance]], [[dido:99_annexes:annex-b-terms-and-definitions:c:control_plane|Control Plane]], [[dido:99_annexes:annex-b-terms-and-definitions:d:data_plane|Data Plane]], generated [[dido:99_annexes:annex-b-terms-and-definitions:a:artifact|Artifact]], [[dido:99_annexes:annex-b-terms-and-definitions:b:baseline|Baseline]], and acceptance Evidence should keep their defined meanings.

Documentation should use complete sentences, correct grammar, and consistent punctuation. Headings should use consistent capitalisation. Lists should use parallel structure where practical. Short, direct sentences are preferable to long sentences with multiple embedded qualifications.

The team should avoid the following in committed Artifacts:

  - Informal wording that weakens technical clarity.
  - Unexplained abbreviations or local shorthand.
  - Personal pronouns, such as “I”, “we”, “you”, “our”, or “your”, unless they appear in quoted material or an explicitly approved communication Artifact.
  - Passive voice where active voice would make the responsible actor clearer.
  - Personal notes that refer to an individual developer rather than the project Baseline.
  - Temporary comments that do not link to an open issue, risk, or decision.
  - Editing-history labels such as “new”, “old”, “final”, “final-final”, or “backup”.
  - Unresolved comments such as “fix later”, “temporary hack”, “not sure why this works”, or “come back to this”.
  - Machine-specific or developer-specific references, such as local paths, usernames, workstation names, or “Nick’s version”.

Such comments or labels should enter the controlled Baseline only when they appear in an explicitly marked open issue, risk, decision record, or troubleshooting note.

Spelling and grammar checks should form part of the review. Reviewers should correct minor issues when practical and request a revision when unclear writing affects [[dido:99_annexes:annex-b-terms-and-definitions:t:traceability|Traceability]], reproducibility, reviewability, or Evidence of acceptance.

----

<WRAP centeralign>

© 2026 Dido Solutions, Inc. and Jackrabbit Consulting, Inc.

</WRAP>