| name | english-document-writing |
| model | sonnet |
| description | Apply Bajutsu's English prose mechanics when writing, translating, or revising English roadmap items and documentation. Use it together with document-writing. |
Technical-writing norm for English prose
This skill is the English layer of Bajutsu's prose norm. It holds the mechanics that only English
grammar and typography need — the choices that have a single right answer in English and no
counterpart in Japanese.
It sits beneath the language-agnostic document-writing skill. When you
write or revise English prose, apply both: document-writing for the writing technique both
languages share (top-down drafting, sentence stress, subject–verb proximity, active voice, cutting
filler), and this skill for the English mechanics below. Invoke both before you write, not
after. These mechanics never apply to Japanese — Japanese has its own dash and punctuation rules,
in japanese-document-writing, the sibling layer beneath the same
umbrella.
Like the rest of the prose norm, this is a review-time expectation checked by people, not a CI gate
(prime directive 1 keeps an LLM off the run / CI verdict path).
English-specific mechanics
- Formal word choice. Use "many" or "much", not "a lot of". Spell out contractions in formal
text. Reserve symbols and abbreviations for formulas; in prose, spell out the word (write "for
all", not "∀"; "such that", not "s.t.").
- Serial (Oxford) comma. In a list of three or more items, put a comma before the final "and"
or "or": "the driver, the runner, and the reporter".
- That vs. which. Use that (no comma) for a restrictive clause that specifies which thing you
mean. Use which (set off by commas) for a non-restrictive clause that adds information not
needed to identify the thing.
- No bare "this" / "that" as a noun. Name what it points to: "this behavior", "that
constraint", not a lone "this".
- No singular "they" for an unspecified single person. Reword to the plural ("reviewers raise
their hands") or a role, rather than "each reviewer raised their hand".
- Dashes. A hyphen joins a compound adjective ("capability-aware selection"). An en-dash marks a
range ("steps 3–7") with no surrounding spaces. An em-dash sets off an aside for emphasis — with a
space on each side, per this repo's own convention (Chicago itself specifies no space).
- Numbers. Spell out a positive whole number below ten used as an adjective ("three drivers");
use the numeral when it is a noun or ten or above.
- Colon. Introduce a list or an elaboration with a colon only after a complete sentence.
Words this repo's textlint flags
This repo's write-good, stop-words, and alex checks flag specific constructs. They live at
tools/textlint/. Write around them from the start; do not wait to
discover them at the verification pass.
- Passive voice. Some forms get flagged, like "is set" or "are coupled". Name the actual agent
as the subject. Write "the caller sets the flag". Skip "the flag is set".
- "only", "therefore", "exclusively", "solely". Each is a common word. Each still gets flagged,
as weakening, wordy, or a stop word. Try "purely" or "merely" in its place. A rewrite with
"alone" works too — "that lane alone provides...". Confirm a substitute against the config
first. A near-synonym can trip a different rule than the one you meant to dodge.
- A sentence-initial "So". This gets flagged for adding no meaning. Drop the opener.
- "it is" / "there is". Both get flagged as unnecessary verbiage. Restate with a real subject.
alex produces false positives. Plain words can get flagged: "easy", "trap", "failure",
"just". The check targets biased language, not technical prose. Reword it when a clean substitute
exists. Try "issue" for "trap". Try "what breaks" for "the failure mode". Skip an awkward rewrite
when the flagged word is genuinely the clearest term.
Verify your work
Reread the English draft once against the mechanics above, alongside the language-agnostic reread in
document-writing. Then run the mandatory
textlint check — the runtime and rules live at
tools/textlint/, cover English prose too, and are documented in
document-writing's textlint section.
Keep revising and rerunning until every finding is gone; textlint is a mechanical floor, not a
substitute for the norms above.
References
- Jeffrey Scott Vitter, Structure + Style = Communication (The University of Kansas, 2011) — the
source of the English mechanics above.
document-writing — the language-agnostic umbrella above this layer.japanese-document-writing — the Japanese sibling layer.
