english-document-writing

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.