managing-docs

Managing Documentation Skill

You are an expert at organizing, structuring, and managing documentation across software projects.

When This Skill Activates

This skill auto-invokes when:

• User asks about documentation structure or organization
• User wants to set up documentation for a project
• User needs to configure documentation tools (Sphinx, MkDocs, etc.)
• User asks about documentation best practices for organization
• User wants to restructure existing documentation

Documentation Architecture Patterns

Pattern 1: Simple Project (README-Centric)

Best for: Small projects, libraries, single-purpose tools

project/
├── README.md           # Main documentation
├── CONTRIBUTING.md     # Contribution guidelines
├── CHANGELOG.md        # Version history
├── LICENSE             # License file
└── docs/
    └── api.md          # API reference (if needed)

Pattern 2: Standard Project (Docs Directory)

Best for: Medium projects, applications with multiple features

project/
├── README.md           # Overview and quick start
├── CONTRIBUTING.md
├── CHANGELOG.md
├── LICENSE
└── docs/
    ├── index.md        # Documentation home
    ├── getting-started.md
    ├── installation.md
    ├── configuration.md
    ├── usage/
    │   ├── basic.md
    │   └── advanced.md
    ├── api/
    │   ├── index.md
    │   └── [module].md
    ├── guides/
    │   └── [topic].md
    └── troubleshooting.md

Pattern 3: Large Project (Full Documentation Site)

Best for: Large projects, frameworks, platforms

project/
├── README.md
├── CONTRIBUTING.md
├── CHANGELOG.md
├── LICENSE
└── docs/
    ├── mkdocs.yml          # Doc site config
    ├── index.md
    ├── getting-started/
    │   ├── index.md
    │   ├── installation.md
    │   ├── quick-start.md
    │   └── first-project.md
    ├── guides/
    │   ├── index.md
    │   └── [topic]/
    │       └── index.md
    ├── reference/
    │   ├── index.md
    │   ├── api/
    │   ├── cli/
    │   └── configuration/
    ├── tutorials/
    │   └── [tutorial]/
    ├── concepts/
    │   └── [concept].md
    ├── examples/
    │   └── [example]/
    └── contributing/
        ├── index.md
        ├── development.md
        └── style-guide.md

Pattern 4: Monorepo Documentation

Best for: Monorepos with multiple packages

monorepo/
├── README.md               # Monorepo overview
├── docs/
│   ├── index.md           # Overall documentation
│   ├── architecture.md
│   └── packages.md
└── packages/
    ├── package-a/
    │   ├── README.md      # Package-specific docs
    │   └── docs/
    └── package-b/
        ├── README.md
        └── docs/

Documentation Types

1. Reference Documentation

• API documentation
• Configuration options
• CLI commands
• Data types and schemas

Characteristics:

• Comprehensive and exhaustive
• Organized alphabetically or by module
• Auto-generated when possible
• Linked from tutorials and guides

2. Conceptual Documentation

• Architecture overviews
• Design decisions
• How things work internally
• Theoretical background

Characteristics:

• Explains the "why"
• Provides context
• Uses diagrams when helpful
• Links to reference docs

3. Procedural Documentation (How-To Guides)

• Step-by-step instructions
• Task-oriented content
• Specific goals in mind
• Common workflows

Characteristics:

• Numbered steps
• Clear prerequisites
• Expected outcomes
• Troubleshooting tips

4. Tutorial Documentation

• Learning-oriented content
• Hands-on exercises
• Progressive complexity
• Complete examples

Characteristics:

• Beginner-friendly
• Self-contained
• Working code included
• Builds on previous steps

Documentation Tools Setup

MkDocs (Python Projects)

Installation:

pip install mkdocs mkdocs-material

Basic mkdocs.yml:

site_name: Project Name
theme:
  name: material
  features:
    - navigation.tabs
    - navigation.sections
    - search.highlight

nav:
  - Home: index.md
  - Getting Started:
    - Installation: getting-started/installation.md
    - Quick Start: getting-started/quick-start.md
  - Guides:
    - guides/index.md
  - API Reference:
    - reference/index.md

plugins:
  - search
  - autorefs

markdown_extensions:
  - pymdownx.highlight
  - pymdownx.superfences
  - admonition
  - toc:
      permalink: true

Commands:

mkdocs serve      # Local development server
mkdocs build      # Build static site
mkdocs gh-deploy  # Deploy to GitHub Pages

Docusaurus (JavaScript Projects)

Installation:

npx create-docusaurus@latest docs classic

Key Configuration (docusaurus.config.js):

module.exports = {
  title: 'Project Name',
  tagline: 'Project tagline',
  url: 'https://your-domain.com',
  baseUrl: '/',
  themeConfig: {
    navbar: {
      title: 'Project',
      items: [
        { to: '/docs/intro', label: 'Docs', position: 'left' },
        { to: '/blog', label: 'Blog', position: 'left' },
      ],
    },
  },
};

Sphinx (Python API Docs)

Installation:

pip install sphinx sphinx-rtd-theme
sphinx-quickstart docs

conf.py Setup:

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

html_theme = 'sphinx_rtd_theme'

# Napoleon settings for Google-style docstrings
napoleon_google_docstring = True
napoleon_numpy_docstring = False

TypeDoc (TypeScript Projects)

Installation:

npm install typedoc --save-dev

typedoc.json:

{
  "entryPoints": ["src/index.ts"],
  "out": "docs/api",
  "exclude": ["**/*.test.ts"],
  "excludePrivate": true,
  "includeVersion": true
}

Documentation Standards

File Naming Conventions

✓ getting-started.md      # Lowercase with hyphens
✓ api-reference.md        # Clear and descriptive
✓ installation.md         # Single word when possible

✗ GettingStarted.md       # No PascalCase
✗ getting_started.md      # No underscores
✗ GETTING-STARTED.md      # No all caps (except special files)

Special Files

README.md       # Project overview (required)
CONTRIBUTING.md # Contribution guidelines
CHANGELOG.md    # Version history
LICENSE         # License text
CODE_OF_CONDUCT.md # Community standards
SECURITY.md     # Security policy

Documentation Structure Checklist

Project Root:

• README.md with overview and quick start
• CONTRIBUTING.md with contribution guidelines
• CHANGELOG.md with version history
• LICENSE file

Documentation Directory:

• Clear navigation structure
• Getting started guide
• API/reference documentation
• Examples directory
• Search functionality (if using doc site)

Individual Documents:

• Clear title
• Table of contents (for long docs)
• Logical section organization
• Code examples where relevant
• Links to related content

Versioned Documentation

For projects with multiple versions:

Strategy 1: Branch-Based

docs/
├── latest/           # Symlink to current version
├── v2.0/
├── v1.5/
└── v1.0/

Strategy 2: Docusaurus Versioning

npm run docusaurus docs:version 1.0

Strategy 3: ReadTheDocs Versioning

Automatic version switching based on git tags.

Migration Strategies

Migrating to Docs Directory

1. Create docs/ directory structure
2. Move inline docs to appropriate files
3. Update links and references
4. Add navigation configuration
5. Set up doc site generator (if using)
6. Redirect old documentation URLs

Consolidating Documentation

1. Audit all existing documentation
2. Identify duplicates and conflicts
3. Create canonical versions
4. Remove or redirect duplicates
5. Update all internal links

Automation

GitHub Actions for Docs

name: Deploy Documentation

on:
  push:
    branches: [main]
    paths:
      - 'docs/**'

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.x'
      - run: pip install mkdocs-material
      - run: mkdocs gh-deploy --force

Pre-commit Hooks for Docs

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/igorshubovych/markdownlint-cli
    rev: v0.37.0
    hooks:
      - id: markdownlint
        args: ['--fix']

Integration

This skill works with:

• analyzing-docs skill for assessing current documentation state
• writing-docs skill for creating documentation content
• docs-analyzer agent for comprehensive documentation projects