Documentation Standards

Root-Level Files

Certain files belong in the project root for maximum visibility and tooling support:

Why Root Level?

• GitHub, GitLab, and npm automatically detect and surface these files
• Tools like standard-version and semantic-release expect CHANGELOG.md at root
• Package managers validate LICENSE location
• Improves discoverability for new contributors

Directory Structure

All other documentation lives in /docs/:

/                                  # Project root
├── README.md                      # Project overview (GitHub displays)
├── CHANGELOG.md                   # Version history (single source of truth)
├── CONTRIBUTING.md                # How to contribute
├── LICENSE                        # License file
│
└── docs/                          # All documentation
    ├── README.md                  # Documentation index & navigation
    │
    ├── getting-started/           # TUTORIALS (Learning-oriented)
    │   ├── QUICK-START.md         # First steps walkthrough
    │   ├── SETUP-GUIDE.md         # Environment setup
    │   └── PREREQUISITES.md       # Required knowledge/tools
    │
    ├── guides/                    # HOW-TO GUIDES (Task-oriented)
    │   ├── user/                  # End-user guides
    │   └── developer/             # Developer guides
    │       ├── CONTRIBUTING.md    # Code contribution guide
    │       ├── TESTING.md         # How to run tests
    │       └── DEPLOYMENT.md      # Deployment procedures
    │
    ├── reference/                 # REFERENCE (Information-oriented)
    │   ├── api/                   # API documentation
    │   │   ├── ENDPOINTS.md       # Endpoint reference
    │   │   ├── AUTHENTICATION.md  # Auth methods
    │   │   └── ERROR-CODES.md     # Error reference
    │   ├── CONFIGURATION.md       # Config options reference
    │   └── CLI-COMMANDS.md        # Command line reference
    │
    ├── architecture/              # EXPLANATION (Understanding-oriented)
    │   ├── OVERVIEW.md            # System architecture
    │   ├── DESIGN-DECISIONS.md    # ADRs (Architecture Decision Records)
    │   ├── DATA-FLOW.md           # How data moves through system
    │   └── SECURITY.md            # Security model explanation
    │
    ├── technical/                 # Technical specifications
    │   ├── API-SPECIFICATION.md   # Complete API spec with schemas
    │   ├── DATA-MODELS.md         # Data structures and relationships
    │   └── DATABASE-SCHEMA.md     # Database design
    │
    ├── research/                  # Discovery & research findings
    │   ├── README.md              # Research index
    │   └── findings/              # Investigation results
    │
    └── assets/                    # Supporting media
        ├── images/                # Screenshots, photos
        └── diagrams/              # Architecture diagrams

Diataxis Framework

Documentation is organized into four types based on user needs:

The Four Documentation Types

Where Each Type Lives

Documentation Policy

Where to Create Documentation

Critical Rules

1. NEVER create documentation in .claude/ directory
2. ALL new documentation goes in /docs/ structure (except root-level files)
3. ALWAYS prefer editing existing files over creating new ones
4. NEVER create README.md files unless explicitly requested
5. UPDATE docs/README.md index when adding new documents
6. KEEP CHANGELOG.md in project root, not in docs/
7. USE relative links for cross-references within docs/

Required Documents (Minimum Viable Documentation)

Naming Conventions

Files

Folders

Section Headers

Content Standards

Writing Principles

1. Know Your Audience - Adjust technical depth appropriately
2. Be Concise - Respect reader's time
3. Be Specific - Avoid vague statements
4. Be Consistent - Same terms, same format throughout
5. Be Current - Update when things change

Formatting Standards

Architecture-Agnostic Principles

All technical documentation must be architecture-agnostic - it should work regardless of whether the implementation is a PWA, mobile app, desktop application, CLI, or any other platform.

DO Document

DON'T Document

Test Your Documentation

Ask: "Could a developer use this to build a CLI tool that does the same thing?"

• If yes → Good, architecture-agnostic
• If no → Too implementation-specific

Maintenance Practices

Review Cycle

When to Update Documentation

Style Guide

Key Principles

1. Active voice - "The system processes requests" not "Requests are processed"
2. Present tense - "The function returns" not "The function will return"
3. Second person - "You can configure" not "Users can configure"
4. Contractions OK - "Don't use" is friendlier than "Do not use"
5. Oxford comma - "A, B, and C" not "A, B and C"

Cross-Referencing

# Good - relative links within docs/
See [API Specification](technical/API-SPECIFICATION.md) for details.

# Good - root-level files
See [CHANGELOG](/CHANGELOG.md) for version history.

# Bad - absolute filesystem paths
See /home/user/project/docs/technical/API-SPECIFICATION.md

Version Information

When documenting versioned or time-sensitive information:

## Authentication Flow
*Last verified: 2025-01-15 against v2 API*

[Documentation content...]

Customization

Projects can customize these standards by creating configuration files:

Project-Specific Configuration

Create .claude/docs-management.md for project-wide customizations that are shared with the team (committed to version control).

User-Specific Configuration

Create .claude/docs-management.local.md for personal preferences (should be gitignored).

Configuration File Contents

These files can include:

• Additional templates or template locations
• Custom checklist items
• Project-specific naming conventions
• Additional documentation requirements
• Links to company style guides
• Override instructions for specific situations

Example:

# Project Documentation Config

## Additional Templates
- Use `docs/templates/runbook-template.md` for operational docs

## Project-Specific Rules
- All docs must include "Last reviewed: YYYY-MM-DD" header
- API docs require OpenAPI spec link

## Custom Checklist Items
- [ ] Checked by tech writer
- [ ] Added to docs index

Sources and References

• ISO/IEC/IEEE 26514:2022 - International standard for software user documentation
• Diataxis Framework - Documentation architecture framework
• Google Developer Documentation Style Guide

This document is the single source of truth for documentation standards. When in doubt, follow these guidelines.