documentation-best-practices

Documentation Best Practices Skill — Comprehensive Documentation Standards

Overview

This skill provides comprehensive guidance for creating and maintaining project documentation, writing README files, documenting APIs, establishing documentation standards, and building knowledge bases. It includes Markdown, ADRs, API docs, and documentation automation. Based on software documentation certification standards and technical writing best practices.

When to Use

Use this skill when:

• Creating project documentation for new projects
• Writing README files for repositories
• Documenting APIs (REST, GraphQL, gRPC)
• Establishing documentation standards across teams
• Building knowledge bases for organizations
• Creating Architecture Decision Records (ADRs)
• Writing API documentation with OpenAPI/Swagger
• Setting up documentation automation
• Creating documentation templates and styles
• Building documentation websites (Docusaurus, MkDocs)
• Implementing documentation versioning
• Creating documentation for different audiences
• Setting up documentation review processes
• Implementing documentation quality gates
• Creating documentation metrics and KPIs
• Building documentation migration strategies
• Setting up documentation monitoring
• Creating documentation training materials
• Implementing documentation security
• Creating documentation compliance documentation

Do NOT use this skill when:

• Writing code implementation (use developer skill)
• Designing system architecture (use architecture-patterns skill)
• Writing tests (use testing-strategy skill)
• Implementing features (use implementer agent)

Documentation Types

1. README Files

Every project, module, and package needs a README.

# Project Name

**Version:** 1.0.0  
**Status:** Active  
**License:** MIT

## Overview

Brief description of what this project does and why it exists.

## Features

- Feature 1
- Feature 2
- Feature 3

## Quick Start

```bash
# Install dependencies
npm install