# Paw Docs Guidance > Documentation conventions for PAW implementation workflow. Provides Docs.md template structure, include/exclude guidelines, and project documentation update patterns. Use when this capability is needed. - Skill: `tomevault-io/paw-docs-guidance` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/paw-docs-guidance` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/paw-docs-guidance/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/paw-docs-guidance --- # Documentation Guidance ## Docs.md Purpose `Docs.md` is the **authoritative technical reference** for implemented work. It serves as: - The most comprehensive documentation of what was implemented - A standalone technical reference for engineers - The source of truth for understanding how the implementation works - The basis for generating project-specific documentation - Documentation that persists as the go-to reference **Docs.md is NOT**: A list of documentation changes or a changelog. ## Docs.md Template ```markdown # [Work Title] ## Overview [Comprehensive description of what was implemented, its purpose, and the problem it solves] ## Architecture and Design ### High-Level Architecture [Architectural overview, system components, data flow] ### Design Decisions [Key design choices made during implementation and rationale] ### Integration Points [How this implementation integrates with existing systems] ## User Guide ### Prerequisites [What users need before using this implementation] ### Basic Usage [Step-by-step guide for common use cases with examples] ### Advanced Usage [Complex scenarios, customization options, power-user features] ## API Reference ### Key Components [Document reusable components that other code will call] ### Configuration Options [Available settings and their effects] ## Testing ### How to Test [How to exercise the implementation as a human user] ### Edge Cases [Known edge cases and how they're handled] ## Limitations and Future Work [Known limitations, planned improvements, out-of-scope items] ``` ## What to Include Focus Docs.md on information not easily discovered from code: | Include | Why | |---------|-----| | Design decisions and rationale | Not visible in code | | Architecture and integration points | High-level view | | User-facing behavior and usage patterns | User perspective | | How to test/exercise as a human | Verification guidance | | Migration paths and compatibility | Operational knowledge | | Reusable components for other code | API surface | | Edge cases and limitations | Gotchas users should know | ## What NOT to Include Avoid duplicating information already in code or other artifacts: | Exclude | Why | |---------|-----| | Code reproduction | Already in the code | | Every function/class | Internal details | | Exhaustive API docs | Over-documentation | | Test coverage checklists | In PRs and tests | | Acceptance criteria verification | In implementation artifacts | | Project doc updates list | In PR description | | Unnecessary code examples | Only when essential | ## Project Documentation Updates When updating README, CHANGELOG, guides, or API docs, follow these principles: ### Style Matching (CRITICAL) **STUDY FIRST**: Before updating any project documentation: 1. Read multiple existing entries/sections 2. Understand the style, length, and detail level 3. Match it precisely ### CHANGELOG Discipline - Create **ONE entry** for the work, not multiple sub-entries - Follow existing format exactly (bullet style, sentence case, etc.) - Group related changes into a single coherent entry **Example:** ```markdown ## [Unreleased] ### Added - Skills-based architecture for implementation workflow (#164) ``` ### README Discipline - Match section length and detail level of surrounding sections - Don't expand sections beyond the existing style - Keep additions proportional to the significance of the change ### When Uncertain Err on the side of **LESS detail** in project docs. Docs.md contains the comprehensive detail; users can ask for more if needed. ## Surgical Change Discipline - ONLY modify documentation files required to describe the completed work - DO NOT format or rewrite implementation code sections - DO NOT introduce unrelated documentation updates or cleanups - DO NOT remove historical context without explicit direction - When unsure if a change is purely documentation, pause and ask ## Documentation Depth by Workflow Mode | Mode | Docs.md Depth | Project Docs | |------|---------------|--------------| | full | Comprehensive with all sections | Full updates | | minimal | Essential information only | Minimal updates | | custom | Per Custom Workflow Instructions | As specified | ## Quality Checklist Before completing documentation: - [ ] Docs.md covers all sections relevant to the implementation - [ ] Design decisions and rationale documented - [ ] User-facing behavior explained with examples - [ ] No code reproduction or over-documentation - [ ] Project docs match existing style - [ ] CHANGELOG has single coherent entry - [ ] README changes proportional to significance --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/lossyrob) — claim your Tome and manage your conversions.