home / skills / hhopkins95 / ai-systems / documentation-system

documentation-system skill

safe

/plugins/smart-docs-authoring/skills/documentation-system

This skill helps you create and maintain clear, AI-navigable documentation for codebases, guiding structure, content, and updates across docs.

npx playbooks add skill hhopkins95/ai-systems --skill documentation-system

Review the files below or copy the command above to add this skill to your agents.

Files (8)

SKILL.md

2.8 KB

---
name: Documentation System
description: Standards for documenting codebases. Use when writing documentation, deciding where docs should go, reviewing doc quality, or updating docs after code changes. Covers folder structure, content guidelines, and maintenance workflows.
---

# Documentation System

A system for writing clear, maintainable documentation optimized for both humans and AI navigation.

## Core Philosophy

1. **Document logic, not syntax** - Explain how things work together, not what's obvious from code
2. **Progressive disclosure** - Overview first, details on demand
3. **AI-navigable** - Clear structure so AI can find and update the right docs
4. **Minimal but complete** - Include what's needed, nothing more

## Folder Structure

Documentation lives in `docs/` with three top-level folders:

```
docs/
├── index.md          # Entry point: what is this codebase, how to navigate
├── system/           # How the system works (capabilities, concepts, flows)
├── packages/         # Per-package documentation
└── guides/           # Task-oriented how-tos
```

| Folder | Question It Answers |
|--------|---------------------|
| `system/` | "What does this system do? How does X work?" |
| `packages/` | "What does package Y do internally?" |
| `guides/` | "How do I accomplish Z?" |

Each folder has an `index.md` with navigation links and descriptions.

## When to Use Each Reference

Read these for detailed guidance:

| Reference | When to Read |
|-----------|--------------|
| [structure.md](references/structure.md) | Creating new docs, reorganizing, deciding where something goes |
| [content.md](references/content.md) | Writing or reviewing doc content, style questions |
| [maintenance.md](references/maintenance.md) | Code changed, checking if docs need updates |
| [templates/](references/templates/) | Starting a new doc, need a concrete starting point |

## Quick Reference

### Creating a New Doc

1. Determine type: system concept, package doc, or guide
2. Check if it should extend an existing doc instead
3. Use appropriate template from `references/templates/`
4. Add to relevant `index.md` navigation

### Finding Existing Docs

1. Start at `docs/index.md` for overview
2. System-level concepts → `docs/system/`
3. Package specifics → `docs/packages/[package-name].md`
4. How-to instructions → `docs/guides/`

### Updating Docs After Code Changes

1. Identify which docs reference the changed code
2. Check if descriptions are still accurate
3. Update code references (file paths, line numbers if used)
4. Don't remove content without checking cross-references

## What NOT to Document

- Implementation details that change frequently
- Information obvious from well-named code
- Auto-generatable content (API signatures, type definitions)
- Speculative future plans (use project tracking instead)

Overview

This skill defines a Documentation System for clear, maintainable docs tuned for both human readers and AI navigation. It prescribes a minimal folder structure, content guidelines, and maintenance workflows so docs stay useful as code evolves. The approach emphasizes progressive disclosure and documenting intent over implementation noise. Use it to decide where docs belong, how to write them, and when to update them after changes.

How this skill works

Documentation lives under a single docs/ root with three top-level areas: system, packages, and guides, each with an index.md for navigation. Writers select a template, place content in the appropriate folder, and follow rules that favor explaining logic and flows rather than repeating code. Maintenance checks map code changes to affected docs and require updating descriptions and references. The system is organized so both humans and AI agents can find and update the right document quickly.

When to use it

Creating a new document or reorganizing documentation layout.
Writing or reviewing content to decide scope and style.
Updating docs after code changes to keep descriptions accurate.
Choosing whether content belongs in system, packages, or guides.
Onboarding new contributors to learn where to find key information.

Best practices

Start with an overview (progressive disclosure) then add details and examples.
Document intent, system behavior, and flows—avoid restating code or syntax.
Use templates for consistency and add each doc to its folder index.md.
Keep docs minimal but complete; exclude auto-generated or highly volatile details.
Run a quick mapping from changed files to docs after any code change.

Example use cases

Adding a new package: create docs/packages/[package-name].md from template and link it in packages/index.md.
Explaining a system flow: put conceptual diagrams and high-level behavior in docs/system/index.md and deep dives in system/*.md.
Writing a how-to: add a step-by-step guide with examples in docs/guides/ and link to related package docs.
Post-PR doc check: identify touched modules, verify affected docs, and update any stale descriptions.
Deciding placement: consult structure reference to choose between system, package, or guide locations.

FAQ

When should I document code versus system behavior?

Document system behavior, responsibilities, and interactions; skip low-level code syntax or trivial getters/setters that are clear from well-named code.

What belongs in templates?

Templates should include sections for purpose, usage, examples, related links, and maintenance notes to make new docs consistent and AI-navigable.