# 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 local dictionary with this guide.
In this guide, “the dictionary” means `docs/dictionary.md`.
The dictionary defines banned terms and the strict domain allowlist.

## 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 dictionary.
  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:

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

  Use:

  ```text
  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.`