| name | paw-docs-guidance |
| description | Documentation conventions for PAW implementation workflow. Provides Docs.md template structure, include/exclude guidelines, and project documentation update patterns. |
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
# [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:
- Read multiple existing entries/sections
- Understand the style, length, and detail level
- 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:
## [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:
