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.

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

# Run development server
npm run dev

# Run tests
npm test
```

Project Structure

Copy code
project/
├── src/           # Source code
├── tests/         # Test files
├── docs/          # Documentation
└── scripts/       # Automation scripts

Configuration

API Reference

See API Documentation for complete API reference.

Contributing

See Contributing Guide for details.

License

MIT

Copy code

### 2. API Documentation

Document all public APIs.

```markdown
# API Documentation

## Base URL

https://api.example.com/v1

Copy code

## Authentication

All endpoints require authentication via Bearer token.

Authorization: Bearer

Copy code

## Endpoints

### GET /api/v1/users

Retrieve a list of users.

**Query Parameters:**
- `page` (optional): Page number (default: 1)
- `limit` (optional): Items per page (default: 20)
- `sort` (optional): Sort field (default: name)
- `order` (optional): Sort order (asc/desc, default: asc)

**Response:**
```json
{
  "data": [
    {
      "id": "uuid",
      "name": "string",
      "email": "string"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "totalPages": 5
  }
}

POST /api/v1/users

Create a new user.

Request Body:

jsonCopy code
{
  "name": "string (required)",
  "email": "string (required)",
  "password": "string (required)",
  "role": "string (optional, default: user)"
}

Response:

jsonCopy code
{
  "id": "uuid",
  "name": "string",
  "email": "string",
  "role": "string",
  "createdAt": "ISO8601"
}

Error Responses

Copy code

### 3. Architecture Decision Records (ADRs)

Document architecture decisions.

```markdown
# ADR-001: Database Technology Selection

**Date:** 2024-01-15
**Status:** Accepted

## Context

We need to choose a database for our ERP system. The system requires:
- ACID compliance
- Complex queries
- High availability
- Scalability

## Options Considered

### PostgreSQL

**Pros:**
- ACID compliant
- Rich query capabilities
- Strong community
- Good performance

**Cons:**
- Scaling requires more effort
- Learning curve for complex features

### MongoDB

**Pros:**
- Easy scaling
- Flexible schema
- Good for document-based data

**Cons:**
- No ACID compliance (until 4.0)
- Complex queries are harder
- Memory usage

### MySQL

**Pros:**
- Well-understood
- Good performance
- Strong community

**Cons:**
- Limited JSON support
- Scaling challenges

## Decision

**We chose PostgreSQL.**

### Rationale

- ACID compliance is critical for ERP
- Complex queries are common in ERP
- Performance is acceptable
- Community support is strong

### Implementation

- Use PostgreSQL 15
- Enable logical replication
- Set up read replicas
- Implement connection pooling

## Consequences

### Positive

- Data integrity guaranteed
- Complex queries supported
- Good performance for our use case

### Negative

- Scaling requires more effort
- Learning curve for team
- More complex setup

## Next Steps

- Set up production database
- Migrate existing data
- Document database schema
- Train team on PostgreSQL

## References

- [PostgreSQL Documentation](https://www.postgresql.org/docs/)
- [Database Selection Study](https://example.com/study)

4. Module Documentation

Document each business module.

markdownCopy code
# Module Name

**Version:** 1.0.0  
**Domain:** business-domain  
**Bounded Context:** context-name

## Overview

Brief description of the module's purpose and business value.

## Domain Model

### Entities

- `EntityName` - Description
- `EntityName` - Description

### Value Objects

- `ValueObjectName` - Description
- `ValueObjectName` - Description

## API

### Endpoints

- `GET /module-name/` - Description
- `POST /module-name/` - Description

## Integration

### Dependencies

- `module-a` - Purpose
- `module-b` - Purpose

### Dependencies On

- None

## Testing

- Unit tests: `tests/unit/`
- Integration tests: `tests/integration/`

## Documentation

- `API.md` - API documentation
- `DECISIONS.md` - Architecture decisions
- `TESTING.md` - Testing strategy

Documentation Standards

Markdown Style

markdownCopy code
# Headers (PascalCase)

## Section Headers

### Subsections

- Bullet lists
- Numbered lists

`code blocks`

| Tables | Are    | Good |
| ------ | ------ | ---- |
| Use    | them   | for  |
| Data   | tables |      |

> Quotes for emphasis

File Naming

Documentation Locations

Copy code
docs/
├── README.md                    # Main README
├── architecture/
│   ├── decisions/              # ADRs
│   │   ├── ADR-001.md
│   │   └── ADR-002.md
│   └── patterns/               # Architecture patterns
│       ├── layered-architecture.md
│       └── ddd.md
├── api/                        # API documentation
│   ├── v1/
│   │   ├── endpoints/
│   │   └── guides/
│   └── README.md
├── modules/                    # Module documentation
│   ├── inventory/
│   │   ├── README.md
│   │   ├── API.md
│   │   └── DECISIONS.md
│   └── sales/
│       └── ...
├── contributing.md             # Contributing guide
├── code-of-conduct.md          # Code of conduct
└── deployment.md               # Deployment guide

Documentation Maintenance

When to Update

• After any architectural decision
• When adding new APIs
• When changing behavior
• When fixing bugs that change behavior
• When onboarding new team members

Documentation Review

• Review PRs include documentation changes
• Documentation is checked in code review
• Outdated documentation is flagged

Documentation Tools

Static Site Generators

API Documentation

Documentation Automation

Common Anti-Patterns

❌ Bad: Outdated Documentation

markdownCopy code
# ❌ BAD: Outdated example

```typescript
// This example is outdated
const result = oldFunction();
```

✅ GOOD: Updated example

typescriptCopy code
// Current example
const result = newFunction();

Copy code

### ❌ Bad: No Examples

```markdown
# ❌ BAD: No examples
The function processes data.

# ✅ GOOD: With examples
The function processes data:

```typescript
const result = processor.process(data);

Copy code

### ❌ Bad: Too Much Detail

```markdown
# ❌ BAD: Too much detail
1. Open the file
2. Read the content
3. Parse the JSON
4. Validate the schema
5. ...

# ✅ GOOD: Appropriate detail
The function reads and parses a JSON file.

❌ Bad: Missing Status

markdownCopy code
# ❌ BAD: No status

# Project Name

Some description...

# ✅ GOOD: With status

# Project Name

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

Some description...

Documentation Quality Checklist

markdownCopy code
## Documentation Quality Checklist

### README Files

- [ ] Clear project description
- [ ] Quick start instructions
- [ ] Project structure overview
- [ ] Configuration options
- [ ] API reference link
- [ ] Contributing link
- [ ] License information

### API Documentation

- [ ] Base URL specified
- [ ] Authentication explained
- [ ] All endpoints documented
- [ ] Request/response examples
- [ ] Error responses documented
- [ ] Rate limiting information

### ADRs

- [ ] Clear context
- [ ] Options considered
- [ ] Decision documented
- [ ] Rationale explained
- [ ] Consequences listed
- [ ] Next steps defined

### Module Documentation

- [ ] Module purpose clear
- [ ] Domain model documented
- [ ] API endpoints listed
- [ ] Integration points defined
- [ ] Testing strategy explained

Real-World Impact

Before this skill:

• No documentation
• Outdated docs
• Hard to onboard
• Unknown APIs

After this skill:

• Comprehensive documentation
• Up-to-date docs
• Easy onboarding
• Clear APIs

Cross-References

• api-design - For API documentation standards
• designing-architecture - For architecture documentation
• product-owner - For user story documentation

References

• Google Developer Documentation Style Guide
• Microsoft Writing Style Guide
• Docusaurus Documentation
• Markdown Guide