Writing and Documentation Standard¶
This standard applies to all substantive documentation in this repository, company-wide and within every venture, unless a venture-specific standard states a stricter rule.
Direct language¶
Write plainly. Say what is true, what is decided, and what is not decided, without hedging language that obscures which is which. Prefer active voice and concrete subjects ("The Founder approves ADRs" rather than "ADRs are approved through a process").
Structure¶
- Use clear, descriptive headings that a reader can scan to find what they need without reading the whole document.
- Keep paragraphs short — a few sentences focused on one idea. Long, unbroken paragraphs are harder to review and harder to link to precisely.
- Use lists where content is genuinely a list (steps, criteria, examples), not as a substitute for connected reasoning that reads better as prose.
Terminology¶
Use terms as defined in docs/company/terminology.md. Do not introduce a new synonym for an existing defined term (e.g., do not call a "venture" a "business unit" in one document and "venture" in another). If a document needs a term that isn't yet defined, define it in the document or propose adding it to the terminology glossary.
Examples¶
Include an example only where it clarifies something that would otherwise be ambiguous or abstract. Do not add illustrative examples purely for volume — a standard that is already clear does not need three examples to prove it.
Assumptions¶
State assumptions explicitly rather than leaving them implicit. If a document depends on something not yet decided (e.g., "assumes the repository boundary decision in ADR-0007 resolves toward multi-repo"), say so, rather than quietly writing as though it were settled.
Links¶
Use relative links between documents in this repository (e.g., ../governance/authority-and-inheritance.md), not absolute filesystem paths and not file:// URLs. Relative links keep working if the repository is cloned to a different location, and they make it possible to check link validity with simple tooling. Link to an external resource with its full URL, following the citation format in external-research-standard.md.
What to avoid¶
- Startup hype and inflated claims. Do not describe ordinary tools or features as "revolutionary," "game-changing," or similar. Describe what something does, not how impressive it is.
- Excessive jargon. Prefer plain terms over buzzwords. Where a technical term is necessary, use it precisely and consistently — don't reach for jargon to sound more sophisticated than the content requires.
- Repeated "operating system" language. Do not describe this repository, the company, or any venture as an "operating system for X" or similar metaphor. It is imprecise and tends to be repeated uncritically once introduced.
- Artificially formal language. Write like a competent colleague explaining something clearly, not like a legal filing. Formality should come from precision, not from stiff phrasing.
- Unsupported legal or trademark conclusions. Do not assert that a name, brand, or mark is legally available, protectable, or non-infringing unless that conclusion is backed by actual legal review. State uncertainty where it exists (see
docs/company/research-and-evidence-principles.md). - Unsupported commercial forecasts. Do not state revenue, growth, or adoption projections as fact unless they are backed by evidence and clearly labeled as projections. See
commercial-claims-standard.md.