Documentation Standards

Documentation Standards

Based on the team's Code of Conduct for Documentation. Apply these guidelines when writing any document intended for the wiki or team consumption.

Writing Standards

1. Write in English.
2. Explain, don't just describe. State the why, not just the what.
3. Plain language. Avoid jargon unless defined in the document. Platform-specific or uncommon terms should be explained on first use.
4. Active voice, concise sentences. Lead with the subject and action.
5. As much as necessary, as little as possible. Avoid over-documentation that becomes stale quickly. Keep it lean.
6. Don't mirror code. Small code examples are fine for illustration. Don't copy-paste implementation code into docs. The code is documented in the repository with comments.
7. Provide examples, diagrams, or visuals where they aid understanding. Tables and code blocks are preferred over long prose.

Tone and Framing

1. Frame positions as proposals, not conclusions. Present direction, invite alignment.
2. Acknowledge the current state without implying it is wrong. The people who built it are the audience.
3. Avoid postulating. Replace "the platform must", "the only way" with collaborative language: "the platform should", "one approach is".
4. Critique processes and systems, not people or teams.
5. Separate aspiration from assessment. When describing a future state, don't let it read as criticism of the present.

Structure and Formatting

1. Use templates if one exists for the document type (ADR, spec, runbook, meeting note).
2. Table of contents for documents longer than 3 sections.
3. Headings, bullet points, numbered lists, and panels for readability.
4. Collapsible sections for large text blocks or code snippets (use expands/details).
5. Code snippets must be properly formatted with language hints.

Maintenance

1. Review and update documentation when the platform changes.
2. Archive outdated documents clearly. Don't leave stale docs without marking them.
3. Assign ownership. Every document should have a clear maintainer.

Collaboration

1. Document reviews for significant updates to ensure accuracy.
2. Document decisions and rationale during discussions.

Review Etiquette

1. Comment only when content is unclear. Don't nitpick style if meaning is clear.
2. Fix spelling, grammar, and sentence structure directly rather than commenting about them.
3. Communicate directly with the writer. Call rather than start a comment thread.
4. State clearly when the review is done.

Applying These Guidelines

When writing documentation:

• Start with the purpose: what is this document and who is it for?
• Lead with the decision or outcome, then explain the reasoning
• Use tables for comparisons, options, or structured data
• Use code blocks for paths, commands, config examples (keep them short)
• End with next steps or open questions if applicable
• Review against the checklist above before publishing

Source: svnlto/nix-config — distributed by TomeVault.