Org Literate

Prose Standard for Literate Org Documents

Rules for writing and revising prose in this repository's Org documents. Adapted from k16shikano's japanese-tech-writing standard (https://gist.github.com/k16shikano/fd287c3133457c4fd8f5601d34aa817d), translated to English and to the register of a personal configuration narrative.

Formatting

• Fill-wrap paragraphs at roughly 85 columns, matching the surrounding text.
• Org markup: =code= for commands, option paths, and file names; ~verbatim~ for literal values; [[url][description]] for links, with proper nouns kept as the description.
• Fragments of code, diffs, logs, and config belong in src blocks, not inline prose.
• Bold a repo-specific term at its first definition; refer to it in plain text afterwards.

Voice

This configuration is a story told by its owner. The reader is a guest browsing someone's dotfiles, not a student reading a manual.

• Narrate decisions in the first person: "I pin this to 0.9 because the 1.x series broke tangling", not "the package is pinned due to breakage".
• Describe what software does in plain third person: "niri scrolls windows horizontally". First person is for choices, history, and opinions.
• Real history is welcome ("after the second time a brew upgrade broke Emacs, I moved everything to Nix") — but only if it actually happened.
• Avoid "we": there is only one author here. Avoid tutorial imperatives ("install X, then run Y") unless the section genuinely is a procedure.
• Opinions may be blunt. "zsh's completion setup wore me down" is better material than a neutral feature comparison.

Scope per setting

• Most settings need one or two sentences: what it enables and the visible effect.
• Reserve the full problem-and-alternatives account for non-obvious trade-offs: architectural choices, package pins, temporary workarounds, forks.
• Prose explains why and why-not-the-alternative; the code block already shows what. Never paraphrase the code line by line.
• When a fact can be stated as configuration, state it in the code block even if it only repeats a default. An explicit setting is clearer than a sentence about the default.

Paragraphs and argument

• One topic per paragraph. The first sentence tells the reader what the paragraph is about.
• Make the logical link to the previous paragraph explicit at the start ("So", "In practice", "But that same failure…").
• Argue in one direction: handle objections first, then state the conclusion once. Do not conclude, rebut, and re-conclude.
• When rejecting an alternative, give the concrete reason in one sentence — a counterfactual often works ("with zsh I would have needed three plugins for this").

Logical rigor

• Every causal claim carries its mechanism. "Enabling A breaks B" is not an explanation; say through what.
• Do not promise unconditionally what only holds conditionally. Prefer "usually", "as long as", "when X holds" over blanket guarantees.
• Do not flatten hedges into assertions when revising. "This seems to be a scheduler issue" stays hedged unless the surrounding text establishes it.
• One name per concept, document-wide. Once a section introduces a term (profile, feature, overlay), keep using it; do not fall back to vague words like "the tool" or "the AI".
• Distinct things stay distinct: two pins with two different reasons are not "the same workaround applied twice".

Reader load

• In prose, prefer the plain description ("the launcher") over the exact identifier when precision isn't needed; the code block carries the exact names.
• Skip decorative precision — dates, sizes, version numbers — unless the number itself is the point (a 100 MiB request cap that forced a redesign earns its place).
• Before adding a second example or scene, say what the first one didn't cover.
• Keep sentences short. A semicolon joining two clauses is a sign the sentence should be two sentences. Colons for elaboration and parentheses for asides are fine.