dotfiles/docs/dictionary.md

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.