diff --git a/AGENTS.md b/AGENTS.md index e3f8874..2e4b418 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,9 +3,14 @@ ## Commit convention Use Conventional Commits for all commit messages. -Before writing a commit message, please read [[docs/conventional-commits]]. +Before writing a commit message, read `docs/conventional-commits.md`. Do not add agent attribution or co-author trailers. +## Technical writing + +Use `docs/technical-writing.md` and `docs/dictionary.md` for authored prose. +Use the nearest project dictionary for project-specific domain language. + ## Gotchas - When materializing an external specification, standard, or project-maintained convention, use the upstream source instead of reconstructing it from memory. diff --git a/docs/dictionary.md b/docs/dictionary.md new file mode 100644 index 0000000..143b044 --- /dev/null +++ b/docs/dictionary.md @@ -0,0 +1,34 @@ +# Dictionary + +This dictionary records repository-wide language decisions for repository prose. +It applies to comments, user-facing descriptions, commit prose, pull-request prose, and Markdown documentation. + +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. + +Use `USE` for approved terms. +Use `AVOID` for terms that do not belong in repository prose. +Use `REPLACE` for terms that have a preferred substitute. + +| Term | Decision | Replacement | Meaning | +| :--- | :--- | :--- | :--- | +| `i.e.` | REPLACE | `that is` | Latin abbreviation. Unclear to non-native speakers. | +| `e.g.` | REPLACE | `for example` | Latin abbreviation. | +| `etc.` | REPLACE | `and so forth`, `and others` | Latin abbreviation. Vague and non-exhaustive. | +| `vs.` / `versus` | REPLACE | `compared to`, `against` | Latin abbreviation. | +| `via` | REPLACE | `by using`, `through`, `with` | Latin term. Prefer direct prepositions. | +| `ad hoc` | REPLACE | `one-off`, `for this case` | Latin term. Prefer direct wording. | +| `simply` | AVOID | | Subjective filler. Code and concepts are not inherently simple. | +| `just` | AVOID | | Minimizing filler word. | +| `obviously` | AVOID | | Subjective qualifier. | +| `clearly` | AVOID | | Subjective qualifier. | +| `easily` | AVOID | | Subjective qualifier. | +| `properly` | REPLACE | `correctly`, or specify exact behavior | Vague and subjective. State the exact condition. | +| `as necessary` | REPLACE | specify exact condition | Ambiguous. Define the condition explicitly. | +| `very` / `quite` | AVOID | | Empty intensifiers. | +| `basically` | AVOID | | Conversational filler. | +| `actually` | AVOID | | Conversational filler. | +| `really` | AVOID | | Empty intensifier. | +| `furthermore` / `moreover` | REPLACE | `also`, `and` | Overly formal transitional filler. | +| repository root | USE | | The Git work tree root. Use it to resolve repository-relative paths. | diff --git a/docs/technical-writing.md b/docs/technical-writing.md new file mode 100644 index 0000000..56dc1db --- /dev/null +++ b/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 `/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.`