# Zircote Documentation Review Documentation Standards > Documentation Standards - Skill: `tomevault-io/zircote-documentation-review-documentation-standards` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/zircote-documentation-review-documentation-standards` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/zircote-documentation-review-documentation-standards/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - 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/zircote-documentation-review-documentation-standards --- # Documentation Standards Standards and patterns for creating, reviewing, and improving technical documentation. Good documentation reduces support burden, accelerates onboarding, and builds user trust — these standards exist to make that happen consistently. ## Core Quality Principles Documentation fails readers in predictable ways: unclear language forces re-reading, missing context creates dead ends, stale examples break trust, and inconsistent terminology confuses. These four principles address the root causes. ### Clarity - Write for the reader's level of expertise - Define technical terms on first use - Use active voice and direct language — "Configure the server" not "The server should be configured" - Avoid jargon unless the audience expects it ### Completeness - Cover all essential topics for the document's purpose - Include prerequisites and requirements upfront - Provide working examples for technical concepts - Document edge cases, limitations, and known issues ### Accuracy - Verify all technical details against current implementation - Test code examples before including them — broken examples erode trust faster than missing docs - Update documentation when code changes - Remove or clearly mark deprecated content ### Consistency - Follow established style guides (project or industry standard) - Use consistent terminology throughout — same concept, same name everywhere - Maintain uniform formatting and structure - Apply consistent code example styles ## Document Structure ### Standard Sections **README files:** 1. Title and brief description 2. Features/highlights 3. Installation/setup 4. Quick start/usage 5. Configuration options 6. API reference (or link) 7. Contributing guidelines 8. License **Technical guides:** 1. Overview/introduction 2. Prerequisites 3. Step-by-step instructions 4. Examples 5. Troubleshooting 6. Related resources **API documentation:** 1. Endpoint/function description 2. Parameters (required/optional) 3. Request/response formats 4. Code examples 5. Error responses 6. Rate limits/constraints ### Heading Hierarchy Headings serve as both navigation and outline — screen readers, search engines, and table-of-contents generators all depend on correct hierarchy. - H1: Document title (one per document) - H2: Major sections - H3: Subsections - H4: Minor subsections (use sparingly) - Avoid H5/H6 — if you need them, the document likely needs restructuring into separate pages ## Markdown Best Practices ### Code Blocks Always specify language for syntax highlighting: ````markdown ```python def example(): return "highlighted" ``` ```` Use inline code for: - File names: `config.yaml` - Commands: `npm install` - Variable names: `user_id` - Short code references: `return True` ### Links **Internal links:** - Use relative paths: `[Setup](./setup.md)` - Verify links exist and are accurate - Use descriptive link text (not "click here") **External links:** - Include for authoritative sources - Consider link rot (prefer stable URLs) - Add context for why the link is relevant ### Lists **Ordered lists** for sequential steps: 1. First do this 2. Then do this 3. Finally do this **Unordered lists** for non-sequential items: - Feature A - Feature B - Feature C ### Tables Use tables for structured data comparison: | Feature | Free | Pro | |---------|------|-----| | Users | 5 | 100 | | Storage | 1GB | 50GB| Avoid tables for simple lists or prose content. ### Admonitions Use consistent patterns for callouts: ```markdown > **Note:** Additional information > **Warning:** Important caution > **Tip:** Helpful suggestion ``` ## Review Checklist When reviewing documentation, evaluate: ### Content Quality - [ ] Purpose is clear from introduction - [ ] All claims are accurate and verifiable - [ ] Examples are complete and working - [ ] Prerequisites are documented - [ ] Edge cases are addressed ### Structure - [ ] Logical flow from introduction to details - [ ] Appropriate heading hierarchy - [ ] Related content is grouped together - [ ] Navigation is intuitive ### Formatting - [ ] Code blocks have language specified - [ ] Links are valid and descriptive - [ ] Lists are used appropriately - [ ] Tables are well-formatted - [ ] Consistent style throughout ### Accessibility - [ ] Images have alt text - [ ] Color is not sole indicator - [ ] Content works without images - [ ] Headings describe content ## Common Issues ### Outdated Content - **Signs:** Version numbers don't match, deprecated APIs referenced, screenshots show old UI - **Fix:** Update or remove outdated sections, add "last updated" dates ### Missing Context - **Signs:** Assumes knowledge not provided, jumps into details, missing prerequisites - **Fix:** Add introduction, document assumptions, link to prerequisites ### Inconsistent Terminology - **Signs:** Same concept called different names, abbreviations undefined - **Fix:** Create glossary, standardize terms, define on first use ### Broken Examples - **Signs:** Code doesn't compile, commands fail, outputs don't match - **Fix:** Test all examples, update for current versions, add expected outputs ### Poor Organization - **Signs:** Related content scattered, unclear navigation, buried important info - **Fix:** Restructure by topic, add table of contents, move critical info up ## Writing Style Effective technical writing is invisible — readers absorb the information without noticing the prose. These patterns make that happen. ### Voice and Tone - Use active voice: "Configure the server" not "The server should be configured" - Be direct: "Run the command" not "You might want to run the command" - Stay objective: Focus on facts and procedures - Use imperative form for instructions: "Install the package" not "You should install the package" ### Technical Accuracy - Verify all technical claims against current implementation - Include version numbers where relevant — readers need to know if docs match their setup - Test commands and code before documenting - Reference authoritative sources ### Audience Awareness - Define the target audience clearly — who is this document for? - Adjust complexity to match audience expertise - Provide links for background knowledge rather than inline explanations - Don't over-explain basics to experts — it signals the docs aren't for them ## Language Doc Toolchains Language-native documentation toolchains (rustdoc, godoc, Sphinx, TypeDoc, Javadoc/Dokka, DocC, DocFX, ExDoc) generate API reference from source code comments. When a project uses one, in-source doc comments are the authoritative API documentation — not separate markdown files. **General principles:** 1. Source comments are the API reference — not separate markdown files 2. Doc toolchain build must pass clean without warnings or errors 3. All public API must be documented — missing doc comments are a review finding 4. Examples should be testable (doctests, example functions) 5. Pick one doc comment style per project and enforce it For per-language conventions, build commands, review criteria, and configuration examples, see **`references/language-toolchains.md`**. ## Integration with Site Generators When a project uses a documentation site generator, follow its conventions: | Generator | Key Files | Notes | |-----------|-----------|-------| | MkDocs | `mkdocs.yml` | Admonition syntax, search/versioning plugins | | Sphinx | `conf.py` | reStructuredText, autodoc integration | | Docusaurus | `docusaurus.config.js` | MDX support, sidebar config, versioning | | Astro Starlight | `astro.config.mjs` | Content collections in `src/content/docs/`, i18n, component islands | ## Additional Resources ### Reference Files For detailed guidance, consult: - **`references/style-guide.md`** - Comprehensive writing style rules - **`references/review-criteria.md`** - Detailed review criteria and scoring - **`references/language-toolchains.md`** - Per-language doc toolchain conventions (Rust, Go, Python, TypeScript, Java/Kotlin, Swift, C#, Elixir) ### Example Files Working examples in `examples/`: - **`good-readme.md`** - Well-structured README template - **`api-doc-template.md`** - API documentation template --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/zircote) — claim your Tome and manage your conversions.