documentation-standards

What this skill does

# Documentation Standards

This skill provides the structure, policies, and quality standards for all project documentation. **Any human or agent creating documentation must follow these standards.**

*Based on [ISO/IEC/IEEE 26514:2022](https://www.iso.org/standard/77451.html) and the [Diataxis Framework](https://diataxis.fr/).*

## Customization Check

Before applying these standards, check for project-specific customizations:

1. `.claude/docs-management.md` (project-specific, shared with team) - if it exists
2. `.claude/docs-management.local.md` (user-specific, personal preferences) - if it exists

Apply standards in order: **local overrides > project overrides > plugin defaults**

---

## Project File Structure

### Root-Level Files

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

| File | Location | Purpose |
|------|----------|---------|
| `README.md` | `/` (root) | Project overview - GitHub/GitLab displays on homepage |
| `CHANGELOG.md` | `/` (root) | Version history - tools like `semantic-release` expect this |
| `CONTRIBUTING.md` | `/` (root) | Contribution guide - GitHub links in Community tab |
| `LICENSE` | `/` (root) | License file - package managers detect automatically |
| `CODE_OF_CONDUCT.md` | `/` (root) | Community standards - GitHub surfaces in health score |
| `SECURITY.md` | `/` (root) | Security policy - GitHub displays security information |

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

| Type | Purpose | User Need | Characteristics |
|------|---------|-----------|-----------------|
| **Tutorials** | Learning | "I want to learn" | Step-by-step, beginner-focused, works every time |
| **How-to Guides** | Goals | "I want to accomplish X" | Task-focused, assumes knowledge, practical |
| **Reference** | Information | "I need to look up Y" | Factual, complete, consistent structure |
| **Explanation** | Understanding | "I want to understand why" | Conceptual, discusses trade-offs, opinionated |

### Where Each Type Lives

| Diataxis Type | Directory | Examples |
|---------------|-----------|----------|
| Tutorials | `getting-started/` | Quick-start, setup guides |
| How-to Guides | `guides/` | Contributing, testing, deployment |
| Reference | `reference/`, `technical/` | API docs, config options, data models |
| Explanation | `architecture/` | Design decisions, data flow, security model |

---

## Documentation Policy

### Where to Create Documentation

| Document Type | Location | Example |
|--------------|----------|---------|
| Project overview | `/README.md` (root) | Main project description |
| Version history | `/CHANGELOG.md` (root) | Release notes |
| API specifications | `docs/technical/` | API-SPECIFICATION.md |
| Data models | `docs/technical/` | DATA-MODELS.md |
| Architecture explanations | `docs/architecture/` | DESIGN-DECISIONS.md |
| Research findings | `docs/research/` | Investigation results |
| Setup/getting started | `docs/getting-started/` | QUICK-START.md |
| User guides | `docs/guides/user/` | Feature guides |
| Developer guides | `docs/guides/developer/` | Contributing, testing |

### 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)

| Document | Priority | Location |
|----------|----------|----------|
| Project README | **Critical** | `/README.md` |
| Quick start guide | **Critical** | `docs/getting-started/QUICK-START.md` |
| API reference (if applicable) | **Critical** | `docs/reference/api/` |
| Architecture overview | **High** | `docs/architecture/OVERVIEW.md` |
| Contributing guide | **High** | `/CONTRIBUTING.md` or `docs/guides/developer/` |
| CHANGELOG | **High** | `/CHANGELOG.md` |

---

## Naming Conventions

### Files

| Convention | Example | Notes |
|------------|---------|-------|
| UPPERCASE with hyphens | `API-REFERENCE.md` | Standard for docs/ |
| Descriptive names | `AUTHENTICATION-FLOW.md` | Not `AUTH.md` |
| Include version where relevant | `MIGRATION-V2-TO-V3.md` | For upgrade guides |
| Match directory patterns | See existing files | Consistency over preference |

### Folders

| Convention | Example | Notes |
|------------|---------|-------|
| lowercase with hyphens | `getting-started/` | Never camelCase or PascalCase |
| Descriptive purpose | `architecture/` | Not `arch/` |
| Group by purpose | `reference/api/` | Not by file format |

### Section Headers

| Convention | Example | Notes |
|------------|---------|-------|
| Sentence case | "Getting started" | Not "Getting Started" |
| Be specific | "Configure authentication" | Not "Configuration" |
| Action-oriented for guides | "Install dependencies" | Imperative mood |

---

## Content Standards

### Writing Principles

1. **Know Your Audie