60 lines
4.0 KiB
Markdown
60 lines
4.0 KiB
Markdown
# 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/`. Use for one program, service, or subsystem. |
|
|
| 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`. |
|
|
| assembly file | Nix | A Nix file under `flake/` that constructs flake outputs or arguments passed to NixOS modules. |
|
|
| assembly function | Nix | A project function in `flake/` that creates modules, systems, or output values. |
|
|
| library file | Nix | A Nix file that defines reusable project functions instead of a NixOS module or flake output. |
|
|
| library function | Nix | A pure project function exposed under `util`. |
|
|
| NixOS module | Nix | A Nix file evaluated by `nixosSystem` for a NixOS configuration. |
|
|
| 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. |
|