documentation-standards

# 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