Docs-as-Code Skill

Core Philosophy

"Documentation should be treated like code: version-controlled, reviewed, tested, and continuously deployed."

Docs-as-Code means writing documentation with the same tools and workflows as software development.

Fundamental Principles

1. Version Control

Store docs in Git alongside code
Track changes with meaningful commits
Use branches for content development
Review docs via pull requests

2. Plain Text Formats

# Preferred formats:
- Markdown (.md) - Most common, widely supported
- reStructuredText (.rst) - Python ecosystem standard
- AsciiDoc (.adoc) - Technical documentation

# Avoid:
- Word documents
- Google Docs (for primary source)
- PDFs as source (OK as output)

3. Automation

Auto-generate docs from code (docstrings)
Build and deploy via CI/CD
Validate links and formatting
Run spelling and grammar checks

4. Single Source of Truth

One canonical location for each piece of information
Link to authoritative sources, don't duplicate
Update in one place, publish to many

Documentation Hierarchy

Structure documentation from simple to complex:

1. Code itself (good naming = self-documenting)
   ↓
2. Inline comments (explain "why")
   ↓
3. Docstrings (API contracts)
   ↓
4. README.md (entry point, quick start)
   ↓
5. docs/ directory (detailed guides)
   ↓
6. External docs site (comprehensive reference)

README.md Template

# Project Name

One-sentence description of what this project does.

## Quick Start

```bash
pip install project-name

from project import main_function
result = main_function(data)

Installation

Requirements

Python 3.10+
Dependencies listed in pyproject.toml

Install from PyPI

pip install project-name
# Or with uv (faster)
uv pip install project-name

Install from Source

git clone https://github.com/org/project.git
cd project
uv sync  # Install dependencies
cd project
pip install -e .

Usage

Basic Example

[Simple use case with code]

Advanced Example

[More complex use case]

Documentation

Full documentation available at: docs.project.com

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT


## Docs Directory Structure

docs/ ├── index.md # Documentation home ├── getting-started/ │ ├── installation.md │ ├── quickstart.md │ └── configuration.md ├── guides/ │ ├── basic-usage.md │ ├── advanced-topics.md │ └── best-practices.md ├── reference/ │ ├── api.md # Auto-generated from docstrings │ ├── cli.md │ └── configuration.md ├── tutorials/ │ ├── tutorial-1.md │ └── tutorial-2.md ├── contributing/ │ ├── development.md │ ├── testing.md │ └── releasing.md └── changelog.md


## Documentation Tools

### Python Ecosystem
```yaml
# mkdocs.yml for MkDocs
site_name: Project Name
theme:
  name: material
plugins:
  - search
  - mkdocstrings:
      handlers:
        python:
          selection:
            docstring_style: google
nav:
  - Home: index.md
  - Getting Started: getting-started/
  - API Reference: reference/api.md

Sphinx (Python standard)

# conf.py
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'sphinx.ext.viewcode',
]

JavaScript/TypeScript

TypeDoc for TypeScript
JSDoc for JavaScript
Docusaurus for documentation sites

CI/CD Integration

GitHub Actions Workflow

# .github/workflows/docs.yml
name: Documentation

on:
  push:
    branches: [main]
    paths:
      - 'docs/**'
      - 'src/**/*.py'
  pull_request:
    paths:
      - 'docs/**'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install dependencies
        run: pip install -e ".[docs]"

      - name: Build docs
        run: mkdocs build --strict

      - name: Check links
        run: |
          pip install linkchecker
          linkchecker site/

  deploy:
    needs: build
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install mkdocs-material
      - run: mkdocs gh-deploy --force

Documentation Maintenance

When to Update

Same commit as code changes: Documentation stays in sync
Before merging: Block PRs without docs updates for new features
Regularly: Schedule periodic reviews

When to Delete

Delete documentation that is:

Demonstrably incorrect
No longer relevant
Causing confusion
Duplicating other sources

"Fresh, accurate documentation beats extensive outdated materials."

Freshness Indicators

---
last_updated: 2024-01-15
status: current  # or: needs-review, deprecated
applies_to: v2.0+
---

Quality Standards

Link Validation

# Check for broken links
linkchecker docs/
# Or use markdown-link-check
find docs -name "*.md" | xargs markdown-link-check

Spell Checking

# .github/workflows/spellcheck.yml
- name: Spell check
  uses: rojopolis/spellcheck-github-actions@v0
  with:
    config_path: .spellcheck.yml

Style Checking

# Vale for prose linting
vale docs/

Changelog Best Practices

Format (Keep a Changelog)

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/),
and this project adheres to [Semantic Versioning](https://semver.org/).

## [Unreleased]

### Added
- New feature description

### Changed
- Change description

### Fixed
- Bug fix description

## [1.0.0] - 2024-01-15

### Added
- Initial release with core functionality

Documentation Review Checklist

Resources

Write the Docs - Docs as Code
Google Documentation Best Practices
Docs Like Code by Anne Gentle
Modern Technical Writing by Andrew Etter

docs-as-code