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.