name	docs-codebase
description	Technical writing patterns for README files, API documentation, architecture decision records (ADRs), changelogs, contributing guides, code comments, and docs-as-code workflows. Covers documentation structure, style guides, Markdown best practices, and documentation testing.

Technical Documentation — Quick Reference

This skill provides execution-ready patterns for writing clear, maintainable technical documentation. Claude should apply these patterns when users need README files, API docs, ADRs, changelogs, or any technical writing.

Modern Best Practices (2025): Docs-as-code workflows, Markdown standardization, automated changelog generation, ADR (Architecture Decision Records), interactive API docs (OpenAPI 3.2+), documentation testing, accessibility standards (WCAG 2.2), AI-assisted writing (Mintlify, Copilot Docs), video tutorials (Loom, Tango), and docs in version control with CI/CD.

When to Use This Skill

Claude should invoke this skill when a user requests:

Writing README files for projects
Documenting APIs (REST, GraphQL, gRPC)
Creating architecture decision records (ADRs)
Writing changelogs and release notes
Creating contributing guidelines
Documenting code with comments and docstrings
Setting up docs-as-code workflows
Creating user guides and tutorials
Writing technical specifications
Building documentation sites (MkDocs, Docusaurus)

Quick Reference

Documentation Type	Template	Key Sections	When to Use
Project README	readme-template.md	Name, Features, Installation, Usage, Config	New project, open source, onboarding
Architecture Decision	adr-template.md	Status, Context, Decision, Consequences	Technical decisions, trade-offs
API Reference	api-docs-template.md	Auth, Endpoints, Schemas, Errors, Rate Limits	REST/GraphQL APIs, webhooks
Changelog	changelog-template.md	Added, Changed, Deprecated, Removed, Fixed, Security	Releases, version history
Contributing Guide	contributing-template.md	Setup, Commit Guidelines, PR Process, Code Style	Open source, team projects
Code Comments	JSDoc, Python docstrings	Params, Returns, Raises, Examples	Public APIs, complex functions
User Guide	MkDocs/Docusaurus	Getting Started, Tutorials, Troubleshooting	End-user documentation

Decision Tree: Choosing Documentation Type

User needs: [Documentation Task]
    ├─ New project or repository?
    │   └─ **README.md** (project overview, installation, quick start)
    │
    ├─ Made important technical decision?
    │   ├─ Architecture or design choice? → **ADR** (adr-template.md)
    │   └─ Technology choice? → **ADR** with alternatives section
    │
    ├─ Building or documenting API?
    │   ├─ REST API? → **OpenAPI 3.1** spec + api-docs-template
    │   ├─ GraphQL API? → Schema-first + GraphQL Docs
    │   └─ gRPC API? → Protobuf + generated docs
    │
    ├─ Releasing new version?
    │   ├─ Manual changelog? → **CHANGELOG.md** (Keep a Changelog format)
    │   └─ Automated? → semantic-release + Conventional Commits
    │
    ├─ Open source or team collaboration?
    │   ├─ Contribution workflow? → **CONTRIBUTING.md**
    │   ├─ Code of conduct? → CODE_OF_CONDUCT.md
    │   └─ License? → LICENSE file
    │
    ├─ Documenting code?
    │   ├─ Public API/library? → **Docstrings** (JSDoc, Python, etc.)
    │   ├─ Complex logic? → **Comments** (explain WHY, not WHAT)
    │   └─ Architecture? → **README** in module/package + diagrams
    │
    ├─ Building documentation site?
    │   ├─ Python project? → **MkDocs** + Material theme
    │   ├─ JavaScript/React? → **Docusaurus** (versioning support)
    │   └─ Next.js? → **Nextra** (minimal setup)
    │
    └─ Troubleshooting guide?
        └─ Common issues → Solutions → Diagnostic commands → Logs location

Navigation: README Documentation

README Best Practices - `resources/readme-best-practices.md`

Comprehensive guide for creating effective README files with:

Essential 13-section structure (Name, Features, Prerequisites, Installation, Configuration, Usage, etc.)
Copy-paste ready installation commands
Configuration table templates
Troubleshooting patterns
Badge recommendations
Anti-patterns to avoid
README quality checklist

When to use: Creating new project README or improving existing documentation.

Navigation: Architecture Documentation

ADR Writing Guide - `resources/adr-writing-guide.md`

Complete guide for documenting architectural decisions with:

8-section ADR structure (Title, Status, Context, Decision, Consequences, Alternatives, Implementation, References)
Status lifecycle (Proposed → Accepted → Deprecated → Superseded)
How to document trade-offs and alternatives
ADR naming conventions and indexing
When to write vs skip ADRs
Real-world examples with metrics

When to use: Documenting technical decisions like database choice, framework selection, or architecture patterns.

Template: templates/architecture/adr-template.md

Navigation: Changelog Documentation

Changelog Best Practices - `resources/changelog-best-practices.md`

Guide for maintaining changelogs using Keep a Changelog format with:

6 change categories (Added, Changed, Deprecated, Removed, Fixed, Security)
Semantic versioning rules (MAJOR.MINOR.PATCH)
Unreleased section management
Conventional Commits integration
Automated changelog generation (semantic-release, standard-version)
Breaking change communication
Linking to Git commits

When to use: Creating release notes, maintaining version history, documenting breaking changes.

Template: templates/project-management/changelog-template.md

Navigation: API Documentation

API Documentation Standards - `resources/api-documentation-standards.md`

Modern API documentation standards covering:

REST API documentation (OpenAPI 3.1/3.2, authentication, endpoints, errors)
GraphQL API documentation (schema, queries, mutations)
gRPC API documentation (Protocol Buffers, service definitions)
Essential elements (base URL, auth, rate limiting, pagination, webhooks)
Error response format (RFC 7807)
Interactive documentation tools (Swagger UI, Redoc, Stoplight)
Code examples in multiple languages

When to use: Documenting REST, GraphQL, or gRPC APIs for developers.

Template: templates/api-reference/api-docs-template.md

Navigation: Code Comments & Docstrings

Code Commenting Guide - `resources/code-commenting-guide.md`

Comprehensive guide for effective code documentation with:

Core principles (Comment WHY not WHAT, avoid obvious comments, keep updated)
Docstring formats (JSDoc, Python Google Style, TSDoc, Godoc)
Inline comment best practices
When to use documentation vs implementation comments
Comment anti-patterns (commented-out code, redundant comments, changelog comments)
TODO/FIXME/HACK comment standards
Accessibility comments (ARIA labels)

When to use: Documenting code for maintainability, writing public API documentation.

Navigation: Contributing Guidelines

Contributing Guide Standards - `resources/contributing-guide-standards.md`

Guide for creating CONTRIBUTING.md files with:

9-section structure (Welcome, Ways to Contribute, Setup, Workflow, Code Style, Review, Issues, Community, Recognition)
Development setup instructions
Conventional Commits format
Pull request workflow
Code style guidelines (JavaScript, Python, testing)
Code review expectations
Bug reporting and feature request templates
Security vulnerability reporting

When to use: Setting up contribution process for open-source or team projects.

Template: templates/project-management/contributing-template.md

Navigation: Docs-as-Code Workflows

Docs-as-Code Setup - `resources/docs-as-code-setup.md`

Setting up documentation with version control and CI/CD:

MkDocs configuration and Material theme
Docusaurus setup for versioned docs
GitBook integration
GitHub Actions for automated deployment
Documentation site structure
Search and navigation patterns

When to use: Building documentation sites with automated deployment.

Navigation: Writing & Testing

Technical Writing Best Practices - `resources/writing-best-practices.md`

Clear communication principles:

Active voice and conciseness
Plain language guidelines
Audience awareness
Structure and formatting
Writing style consistency

Markdown Style Guide - `resources/markdown-style-guide.md`

Markdown formatting standards:

Syntax reference (headers, lists, code blocks, tables)
Style consistency rules
Link formatting
Code block language tags
Table formatting

Documentation Testing - `resources/documentation-testing.md`

Automated documentation quality checks:

Linting with markdownlint and Vale
Link validation with markdown-link-check
Spell checking with cspell
Code example testing
CI/CD integration

When to use: Establishing documentation standards, automating quality checks.

Templates

Complete copy-paste ready templates organized by domain:

Architecture Documentation

ADR Template: templates/architecture/adr-template.md - Architecture Decision Records for technical decisions

API Reference

API Docs Template: templates/api-reference/api-docs-template.md - REST/GraphQL API documentation with authentication, endpoints, webhooks

Project Management

README Template: templates/project-management/readme-template.md - Project overview, installation, usage
Changelog Template: templates/project-management/changelog-template.md - Keep a Changelog format with semantic versioning
Contributing Guide: templates/project-management/contributing-template.md - Contribution workflow, code standards, commit guidelines

External Resources

See data/sources.json for:

Style Guides: Google Developer Docs, Microsoft Writing Guide, Write the Docs
Documentation Tools: MkDocs, Docusaurus, GitBook, Nextra, Mintlify
API Documentation: OpenAPI, Swagger UI, Redoc, GraphQL Docs
Testing Tools: Vale (prose linting), markdownlint, cspell (spell check), markdown-link-check
Patterns: Keep a Changelog, Semantic Versioning, ADRs, Conventional Commits
Learning: Google Technical Writing Courses, Docs for Developers (book)

Related Skills

Documentation Audit: ../qa-docs-coverage/SKILL.md - Audit codebases for documentation gaps, generate coverage reports, identify what needs documenting
API Design: ../dev-api-design/SKILL.md - REST API patterns, endpoint design, versioning strategies
Code Review: ../software-code-review/SKILL.md - Code review checklists including documentation standards
Testing: ../qa-testing-strategy/SKILL.md - Test documentation patterns, test plan templates
Git Workflow: ../git-workflow/SKILL.md - Commit message standards (Conventional Commits), changelog automation
PRD Development: ../docs-ai-prd/SKILL.md - PRD templates, tech specs, story mapping for new features

Usage Notes

For Claude: When a user requests documentation:

Identify documentation type using the Decision Tree
Reference appropriate template from templates/ directory
Follow best practices from relevant resource file
Provide copy-paste ready content with user's specific context
Include examples from templates or resources
Mention related skills if user might need complementary guidance

Common workflows:

New project: README template → Contributing guide → Changelog
API development: API docs template → OpenAPI spec → Interactive docs
Technical decision: ADR template → Document alternatives → Reference in README
Open source setup: README → CONTRIBUTING.md → CODE_OF_CONDUCT.md → LICENSE

Quality checks:

Verify all links work (use markdown-link-check)
Run spell checker (cspell)
Lint Markdown (markdownlint)
Test code examples actually run
Check accessibility (WCAG 2.2 for web docs)

Success Criteria: Documentation is clear, accurate, up-to-date, discoverable, and enables users to be productive quickly with minimal support.

Install Skill

SKILL.md