docs(repo): add technical writing guide

docs/technical-writing.md

@@ -0,0 +1,113 @@
+# 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:
+
+  ```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.`