SpillwaveSolutions/document-specialist-skill / skills/documentation-specialist
documentation-specialist
VerifiedThis skill should be used when creating professional software documentation (SRS, PRD, OpenAPI, SDD, architecture docs, user manuals, tutorials, runbooks) from templates (greenfield) or reverse-engineering documentation from existing code like Spring Boot or FastAPI (brownfield). Also handles documentation audits/reviews, format conversion (Markdown, DOCX, PDF), and diagram generation (Mermaid first: C4, sequence, class, ER, state, flowchart; PlantUML Salt for UI wireframes and leftover UML). Use when asked to "create documentation", "document my code", "write SRS", "generate PRD", "write DESIGN_DOC.md", "architecture document", "wireframe", or "documentation specialist".
references/reference/01-philosophy.md
View on GitHub# Documentation Philosophy
---
TOKEN_BUDGET: 190
TIER: 3
LOAD_TRIGGER: On-demand when creating any type of documentation
DEPENDENCIES: None
---
## Overview
This guide covers the fundamental philosophy behind effective software documentation: docs-as-code, living documentation, and minimum viable documentation.
---
## 1.1 Living Documentation: The Docs-as-Code Mandate
The most critical failure of traditional documentation is **staleness**. A document that is out of date is worse than no document at all—it actively misleads developers and stakeholders.
**The Bonsai Tree Principle**: Documentation should be "alive but frequently trimmed, like a bonsai tree". Teams must have a culture of "deleting dead documentation" as a continuous process.
**Key Practice:** "Change your documentation in the same commit as the code change." A pull request that adds a new API endpoint must also include the changes to the OpenAPI specification.
---
## 1.2 Minimum Viable Documentation (MVD)
"A small set of fresh and accurate docs is better than a large assembly of 'documentation' in various states of disrepair."
**Focus on:**
- Short, useful documents that are essential for the target audience
- Documents that answer specific questions
- Documentation that reduces support burden
**Avoid:**
- Exhaustive "complete" documentation that becomes unmaintainable
- Documentation that duplicates what the code already expresses
- Over-engineered documentation processes
---
## 1.3 The Three Core Audiences
Documentation is not one-size-fits-all. The content, style, and location depend on **who will be reading it**:
| Audience | Focus | Documents |
|----------|-------|-----------|
| **Stakeholders** | Why & What | PRD, SRS, Use Cases |
| **Developers** | How | SDD, arc42, API Docs, Deployment Docs |
| **End-Users** | How-To | User Guides, KB Articles, Help Centers |
**Critical:** Don't try to force all documentation into a single tool. Developers won't look for API specs where customers look for how-to guides.
---
**End of Documentation Philosophy Guide**
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |