docs: add technical writing guide

docs/dictionary.md

@@ -0,0 +1,55 @@
+# Technical Writing and Domain Dictionary
+
+This dictionary defines project-specific controlled vocabulary, prohibited terms, and domain allowlists.
+It applies to comments, user-facing descriptions, commit prose, pull-request prose, and Markdown documentation in 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.
+
+## Strictly Banned Fluff and Latin Terms
+
+Do not use these Latin abbreviations, conversational filler words, and subjective qualifiers.
+Remove them or use the approved replacements.
+
+| Disapproved Term | Approved Replacement | Notes |
+| :--- | :--- | :--- |
+| `i.e.` | `that is` | Latin abbreviation. Unclear to non-native speakers. |
+| `e.g.` | `for example` | Latin abbreviation. |
+| `etc.` | `and so forth`, `and others` | Latin abbreviation. Vague and non-exhaustive. |
+| `vs.` / `versus` | `compared to`, `against` | Latin abbreviation. |
+| `via` | `by using`, `through`, `with` | Latin term. Prefer direct prepositions. |
+| `ad hoc` | `one-off`, `for this case` | Latin term. Prefer direct wording. |
+| `simply` | omit | Subjective filler. Code and concepts are not inherently simple. |
+| `just` | omit | Minimizing filler word. |
+| `obviously` | omit | Subjective qualifier. |
+| `clearly` | omit | Subjective qualifier. |
+| `easily` | omit | Subjective qualifier. |
+| `properly` | `correctly`, or specify exact behavior | Vague and subjective. State the exact condition. |
+| `as necessary` | specify exact condition | Ambiguous. Define the condition explicitly. |
+| `very` / `quite` | omit | Empty intensifiers. |
+| `basically` | omit | Conversational filler. |
+| `actually` | omit | Conversational filler. |
+| `really` | omit | Empty intensifier. |
+| `furthermore` / `moreover` | `also`, `and` | Overly formal transitional filler. |
+
+## Technical and Domain Allowed Language
+
+Use only approved project-specific terms as controlled vocabulary in documentation and comments.
+Add a term here when repeated project prose needs it.
+Use the simplest accurate word when a term is not listed.
+
+| Approved Domain Term | Category | Description and Permitted Context |
+| :--- | :--- | :--- |
+| agent | Agent tooling | An AI coding assistant acting in the operator's environment. |
+| operator | Agent tooling | The human driving the development process. Use when distinguishing the human from the agent acting on their behalf. |
+| guest | dotfiles | A systemd-nspawn container managed by this flake. Use for configured containers under `guests/`. |
+| host | dotfiles | A machine with a NixOS configuration built by this flake. |
+| module | dotfiles | In this repository, a self-contained configuration under `modules/`, usually scoped to one program, service, or subsystem. Use `Nix module` for the language-level module-system concept. |
+| registry | dotfiles | A typed configuration namespace whose entries can be collected across hosts and reused by other configuration. |
+| Conventional Commits | Git | A commit-message format defined in `docs/conventional-commits.md`. |
+| forge | Git | A web service that hosts Git repositories, pull requests, issues, and code review comments. Use when the exact provider does not matter. |
+| flake | Nix | A Nix project with pinned inputs and declared outputs. Use for the repository-level build unit defined by `flake.nix`. |
+| Nix module | Nix | A Nix language unit that declares or sets options through the Nix module system. |
+| overlay | Nix | A function that modifies a Nix package set by adding or replacing packages. |
+| workspace | Window management | A named or numbered group of windows in a graphical session. Some desktop environments call this a virtual desktop. |

docs/technical-writing.md

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