dev/docs/technical-writing.md

Technical Writing

This guide defines writing rules for comments, user-facing descriptions, commit prose, pull-request prose, and Markdown documentation. These rules apply throughout this repository.

ASD-STE100 Simplified Technical English partly informs these rules. This repository uses those ideas as a local style discipline. It does not claim formal ASD-STE100 compliance.

Read the dictionaries with this guide. In this guide, “the repository dictionary” means docs/dictionary.md at the repository root. The repository dictionary defines repository-wide language decisions for all prose. A project dictionary lives at <project>/docs/dictionary.md. Use the nearest project dictionary between the edited file and the repository root. Project dictionaries define domain-specific language decisions for their subtree. In this guide, “the dictionaries” means the repository dictionary and the project dictionary together.

Structural Conciseness and Grammar Rules

• Clear and concise style: Use direct, concise writing. Use simple present tense for factual descriptions. Do not use uncertainty words such as could, might, and should unless uncertainty is the subject. Use each domain word with the meaning assigned in the dictionaries. Avoid: The tool should usually handle the input correctly. Use: The tool validates the input.
• Avoid jargon and inflated language: Use common technical words. Avoid unnecessary jargon in three categories:
  1. Linguistic and grammatical meta-jargon. Avoid: modal auxiliaries Use: uncertain words
  2. Inflated corporate phrasing. Avoid: utilize Use: use Avoid: commence Use: start
  3. Unapproved domain inventions. Do not use project-specific terms unless the dictionary defines them. General technical words do not need dictionary entries. Add a common word to the dictionary when it has a project-specific meaning. If a term is vague or overloaded, choose one precise term. List avoided alternatives in the dictionary. Choose the simplest word that accurately communicates the meaning.
• Sentence length limits: Code comments, user-facing descriptions, and procedural instructions have a 20-word limit. Descriptive Markdown paragraphs have a 25-word limit. Do not put multiple sentences on one physical line. Wrap a sentence across multiple physical lines when readability requires it. Split long sentences into multiple concise sentences. Avoid: The command configures the service with the generated settings and restarts it after the file changes. Use: The command configures the service with the generated settings. Use: It restarts the service after the file changes.
• Active voice: Always use active voice. The subject must perform the action. Do not use passive voice. Avoid: Stale entries are invalidated by the cache. Use: The cache invalidates stale entries.
• Imperative mood: Procedural instructions and task steps must start with an imperative verb. Summary fragments for declarations use third-person singular. Avoid: The token should be validated before use. Use for a task step: Validate the token before use. Use for a declaration summary: Validates the token before use.
• Noun clusters: Do not write more than three consecutive nouns without a preposition or hyphen. Avoid: session cache entry lookup Use: lookup of session cache entries
• One idea per sentence: Express only one instruction or core concept per sentence. Do not combine multiple operations in one compound sentence. Avoid: Validate the input and restart the service when validation succeeds. Use: Validate the input. Use: Restart the service when validation succeeds.
• Code token exemption: Text in Markdown backticks, URLs, and code blocks counts as one word. Sentence-length limits and noun-cluster limits do not apply to these tokens. Example: curl --fail --silent https://example.com/health counts as one word.
• Cause and time precision: Use because for causality. Use since only for passage of time. Use as only for simultaneous action. Avoid: Since the token is expired, validation fails. Use: Because the token is expired, validation fails.

In-Code Documentation Conventions

• Declaration coverage and exemptions: Document public interfaces, configuration options, fields, and non-trivial public methods. Omit comments on obvious declarations when the name and context are self-explanatory. Avoid: Enable this option. Use: Enables automatic cleanup after a successful run.

• Declaration non-redundancy: Comments must explain purpose, preconditions, invariants, or non-obvious consequences. Do not repeat information that the name, type, path, or parameter list already conveys. Avoid: The timeout option sets the timeout. Use: Controls how long the command waits before it reports failure.

• Multi-line declaration comments: Start multi-line declaration comments with one summary sentence. Put a blank line between the summary and detail paragraphs. Use detail paragraphs for preconditions, invariants, examples, and non-obvious consequences. Avoid:

  The caller must load the signing key before calling this method.
  Validates the token and returns false for expired tokens.
  

  Use:

  Validates the token.
  
  The caller must load the signing key before calling this method.
  Expired tokens return false instead of an error.
  

• Code symbol references: Enclose identifiers, paths, commands, option names, and file names in Markdown backticks. Avoid: Run npm test before editing package.json. Use: Run npm test before editing package.json.

• Boolean descriptions: Start boolean descriptions with the behavior verb. Use True if only when the value reports state instead of enabling behavior. Avoid: Flag that specifies whether retries are enabled. Use: Enables retry behavior. Use for state: True if the token is expired.