# Documentation Standards

> Documentation code of conduct. Use when writing, reviewing, or editing documentation for the wiki, ADRs, specs, or any team-facing documents. Use when this capability is needed.

- Skill: `tomevault-io/documentation-standards-5` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/documentation-standards-5`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/documentation-standards-5/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/documentation-standards-5

---


# 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](https://github.com/svnlto/nix-config) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-15 -->