dev/docs/dictionary.md

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.
agent	USE		An AI coding assistant acting in the operator's environment.
operator	USE		The human driving the development process. Use when distinguishing the human from the agent acting on their behalf.
guest	USE		A systemd-nspawn container managed by the NixOS configuration.
host	USE		A machine with a NixOS configuration built by this repository's flake.
module	USE		A self-contained NixOS configuration under configs/nixos/modules/.
registry	USE		A typed configuration namespace whose entries can be collected across hosts and reused by other configuration.
Conventional Commits	USE		A commit-message format defined in docs/conventional-commits.md.
forge	USE		A web service that hosts Git repositories, pull requests, issues, and code review comments. Use when the exact provider does not matter.
flake	USE		A Nix project with pinned inputs and declared outputs. Use for the repository-level build unit defined by flake.nix.
NixOS module	USE		A Nix file evaluated by nixosSystem for a NixOS configuration.
overlay	USE		A function that modifies a Nix package set by adding or replacing packages.
workspace	USE		A named or numbered group of windows in a graphical session. Some desktop environments call this a virtual desktop.