alexion/dev
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(repo): add technical writing guide

Browse Source
This commit is contained in:
alexion
2026-08-30 08:30:34 -04:00
parent d05bb4857e
commit b9f8f6a626
3 changed files with 153 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

34
docs/dictionary.md Normal file
View File

@@ -0,0 +1,34 @@
# 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. |