4.0 KiB
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. |