Documentation Standards

Memory Operations

You have PERSISTENT MEMORY across sessions.

BEFORE starting any task:

if [ -d ~/.claude/mnemonic ]; then
    rg -i "{documentation_standards}" ~/.claude/mnemonic/ --glob "*.memory.md" -l | head -5
fi

If results exist, READ the most relevant and apply that context.

AFTER completing work, if you discovered:

• •A decision → capture to _semantic/decisions
• •A pattern → capture to _procedural/patterns
• •A learning → capture to _semantic/knowledge
• •A blocker → capture to _episodic/blockers

Guidance for creating, reviewing, and improving technical documentation with focus on quality, clarity, and maintainability.

Core Quality Principles

Clarity

• •Write for the reader's level of expertise
• •Define technical terms on first use
• •Use active voice and direct language
• •Avoid jargon unless necessary for the audience

Completeness

• •Cover all essential topics for the document's purpose
• •Include prerequisites and requirements
• •Provide working examples for technical concepts
• •Document edge cases and limitations

Accuracy

• •Verify all technical details against current implementation
• •Test code examples before including them
• •Update documentation when code changes
• •Remove or mark deprecated content clearly

Consistency

• •Follow established style guides (project or industry standard)
• •Use consistent terminology throughout
• •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

Follow semantic heading structure:

• •H1: Document title (one per document)
• •H2: Major sections
• •H3: Subsections
• •H4: Minor subsections (use sparingly)
• •Avoid H5/H6 (indicates need for restructuring)

Markdown Best Practices

Code Blocks

Always specify language for syntax highlighting:

```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:

Avoid tables for simple lists or prose content.

Admonitions

Use consistent patterns for callouts:

> **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

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

Technical Accuracy

• •Verify all technical claims
• •Include version numbers where relevant
• •Test commands and code before documenting
• •Reference authoritative sources

Audience Awareness

• •Define the target audience clearly
• •Adjust complexity to match audience
• •Provide links for background knowledge
• •Don't over-explain basics to experts

Integration with Site Generators

MkDocs

• •Follow mkdocs.yml navigation structure
• •Use MkDocs-specific admonition syntax
• •Leverage plugins (search, versioning)

Sphinx

• •Use reStructuredText conventions
• •Follow cross-reference patterns
• •Integrate with autodoc for API docs

Docusaurus

• •Use MDX features appropriately
• •Follow sidebar configuration
• •Leverage versioning features

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

Example Files

Working examples in examples/:

• •good-readme.md - Well-structured README template
• •api-doc-template.md - API documentation template