Skip to content

SpillwaveSolutions/document-specialist-skill / skills/documentation-specialist

documentation-specialist

Verified

This 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".

FileKindSize
SKILL.mdskill md10.0 KB
references/examples/TOC.mdmarkdown6.5 KB
references/examples/brownfield/database-failover-runbook.mdmarkdown8.1 KB
references/examples/brownfield/spring-boot-sdd.mdmarkdown5.6 KB
references/examples/greenfield/adr-microservices.mdmarkdown6.3 KB
references/examples/greenfield/architecture-doc.mdmarkdown3.7 KB
references/examples/greenfield/billing-srs.mdmarkdown12.4 KB
references/examples/greenfield/cli-getting-started.mdmarkdown9.3 KB
references/examples/greenfield/collaboration-prd.mdmarkdown13.8 KB
references/examples/greenfield/document-specialist-sdd.mdmarkdown15.4 KB
references/examples/greenfield/ecommerce-sdd.mdmarkdown7.8 KB
references/examples/greenfield/rest-api-tutorial.mdmarkdown13.8 KB
references/examples/greenfield/task-api-openapi.yamlconfig19.0 KB
references/examples/greenfield/taskmanager-user-manual.mdmarkdown8.7 KB
references/examples/greenfield/ui-wireframes.mdmarkdown5.8 KB
references/guides/requirements/README.mdmarkdown3.7 KB
references/mappings/backend/fastapi-mapping.yamlconfig9.7 KB
references/mappings/backend/spring-boot-mapping.yamlconfig24.1 KB
references/reference/01-philosophy.mdmarkdown2.0 KB
references/reference/02-requirements-srs-vs-prd.mdmarkdown1.2 KB
references/reference/02-requirements-traceability.mdmarkdown1.7 KB
references/reference/02-requirements-writing.mdmarkdown1.4 KB
references/reference/03-design-adrs.mdmarkdown2.2 KB
references/reference/03-design-arc42.mdmarkdown2.6 KB
references/reference/03-design-requirements-matrix.mdmarkdown1.3 KB
references/reference/04-diagrams-c4-hierarchy.mdmarkdown2.0 KB
references/reference/04-diagrams-selection.mdmarkdown5.1 KB
references/reference/04-diagrams-state-vs-activity.mdmarkdown2.3 KB
references/reference/05-api-checklist.mdmarkdown2.0 KB
references/reference/05-api-openapi.mdmarkdown3.4 KB
references/reference/05-api-stripe-gold-standard.mdmarkdown1.8 KB
references/reference/06-deployment-diagrams.mdmarkdown1.8 KB
references/reference/06-deployment-documentation.mdmarkdown2.9 KB
references/reference/06-deployment-runbooks.mdmarkdown2.5 KB
references/reference/06-operational-docs.mdmarkdown2.7 KB
references/reference/07-user-kb-approach.mdmarkdown1.8 KB
references/reference/07-user-kb-template.mdmarkdown3.1 KB
references/reference/07-user-writing-style.mdmarkdown2.0 KB
references/reference/08-agile-process.mdmarkdown3.2 KB
references/reference/08-tutorial-writing.mdmarkdown7.4 KB
references/reference/09-code-to-docs-detection.mdmarkdown2.5 KB
references/reference/09-code-to-docs-example.mdmarkdown3.2 KB
references/reference/09-code-to-docs-when.mdmarkdown1.7 KB
references/reference/09-code-to-docs-workflow.mdmarkdown2.0 KB
references/reference/10-quality-bonsai-pruning.mdmarkdown2.4 KB
references/reference/10-quality-checklist.mdmarkdown2.6 KB
references/reference/10-quality-metrics.mdmarkdown3.1 KB
references/reference/11-voice-and-style.mdmarkdown1.5 KB
references/reference/comprehensive-guide.mdmarkdown7.3 KB
references/templates/markdown/DESIGN_DOC.mdmarkdown4.5 KB
references/templates/markdown/api-openapi.yamlconfig17.7 KB
references/templates/markdown/architecture.mdmarkdown1.6 KB
references/templates/markdown/design-sdd.mdmarkdown143 B
references/templates/markdown/developer-tutorial.mdmarkdown7.1 KB
references/templates/markdown/getting-started.mdmarkdown6.5 KB
references/templates/markdown/howto-guide.mdmarkdown4.1 KB
references/templates/markdown/requirements-prd.mdmarkdown10.2 KB
references/templates/markdown/requirements-srs.mdmarkdown17.0 KB
references/templates/markdown/runbook.mdmarkdown8.8 KB
references/templates/markdown/user-manual.mdmarkdown4.8 KB
references/workflows/TOC.mdmarkdown1.9 KB
references/workflows/audit-workflow.mdmarkdown2.5 KB
references/workflows/brownfield-workflow.mdmarkdown3.6 KB
references/workflows/brownfield/fastapi-guide.mdmarkdown1.8 KB
references/workflows/brownfield/pulumi-guide.mdmarkdown1.9 KB
references/workflows/brownfield/springboot-guide.mdmarkdown2.2 KB
references/workflows/convert-workflow.mdmarkdown1.4 KB
references/workflows/design-workflow.mdmarkdown3.0 KB
references/workflows/diagram-workflow.mdmarkdown3.7 KB
references/workflows/greenfield-workflow.mdmarkdown3.4 KB
references/workflows/greenfield/advanced.mdmarkdown1.9 KB
references/workflows/greenfield/openapi-guide.mdmarkdown2.5 KB
references/workflows/greenfield/prd-guide.mdmarkdown2.0 KB
references/workflows/greenfield/srs-guide.mdmarkdown2.0 KB
references/workflows/runbook-workflow.mdmarkdown2.4 KB
references/workflows/tutorial-workflow.mdmarkdown2.3 KB
references/workflows/user-docs-workflow.mdmarkdown2.3 KB

references/reference/08-tutorial-writing.md

View on GitHub
# Tutorial Writing Best Practices

**Version**: 1.0.0
**Token Budget**: ~450 tokens
**Last Updated**: 2025-01-18

---

## Overview

This guide covers best practices for writing three types of learning-focused documentation:
1. **User Manuals**: Comprehensive reference for end-users
2. **How-To Guides**: Task-oriented instructions
3. **Developer Tutorials**: Project-based learning for technical audiences

---

## Document Type Distinctions

| Aspect | User Manuals | How-To Guides | Developer Tutorials |
|--------|--------------|---------------|---------------------|
| **Purpose** | Reference, troubleshooting | Complete specific task | Teach concepts/skills |
| **Structure** | Modular by feature | Step-by-step single task | Progressive narrative |
| **Audience** | End-users (broad) | End-users (focused) | Developers/technical |
| **Tone** | Neutral, instructional | Friendly, direct | Conversational, explanatory |
| **Examples** | Use cases, workflows | Screenshots per step | Code, sample projects |

---

## User Manual Best Practices

### Structure
```
1. Introduction (What & Who)
2. Getting Started (Quick Win < 5 min)
3. Features Reference (Modular sections)
4. Troubleshooting & FAQ
5. Support Resources
```

### Key Principles
- **Modular**: Each feature in own section
- **Scannable**: Headings, bullets, tables
- **Visual**: Screenshot for every UI interaction
- **Accessible**: WCAG-compliant (alt text, headings)

### Tone
- Second person ("you")
- Active voice ("Click Save" not "Save is clicked")
- Define jargon or link to glossary
- Explain "why" not just "how"

---

## How-To Guide Best Practices

### Structure
```
1. Problem Statement (What task)
2. Prerequisites
3. Step-by-Step Instructions (numbered)
4. Visual Aids (screenshots)
5. Verification (How to confirm success)
6. Related Guides (next steps)
```

### Key Principles
- **Atomic**: One task per guide
- **Concrete**: Realistic examples
- **Current**: Last updated date visible
- **Focused**: No tangents

### Visual Guidelines
- Screenshot at each key step
- Annotate images (arrows, highlights)
- Alt text for accessibility
- Consistent zoom/resolution

---

## Developer Tutorial Best Practices

### Structure
```
1. Learning Objective (What you'll build)
2. Prerequisites (knowledge, tools)
3. Project Setup (< 5 min to working state)
4. Progressive Steps (each builds on previous)
5. Testing & Verification
6. Extensions & Next Steps
```

### Key Principles
- **Progressive**: Simple → Complex
- **Tested**: All code examples work
- **Explanatory**: Explain WHY before HOW
- **Interactive**: Checkpoints to verify progress

### Code Quality
- Syntax highlighting with language tags
- Complete, runnable code (not fragments)
- Include imports/dependencies
- Comment complex logic
- Follow style guides (PEP 8, ESLint)

### Checkpoint Pattern
```markdown
## Checkpoint: Verify API Connection
Run this command:
```bash
curl http://localhost:3000/health
```

Expected: `{"status":"ok"}`
✅ If you see this, proceed!
```

---

## Getting Started Guide Best Practices

### Structure
```
1. Introduction (What & Why)
2. Quick Start (< 5 min, copy-paste commands)
3. Core Concepts (key terminology)
4. First Project (hands-on)
5. FAQ
6. Next Steps
```

### Quick Start Requirements
- Commands ready for copy-paste
- Clear expected output
- Verification step
- Under 5 minutes total

### Core Concepts Section
- Define 3-5 key terms
- Simple explanations
- No jargon without definition

---

## CLI Documentation Best Practices

### Required Sections
1. **Installation** (multiple methods)
2. **Usage Overview** (syntax)
3. **Commands Reference** (each command detailed)
4. **Configuration** (files, env vars)
5. **Examples** (common workflows)
6. **Error Handling** (exit codes)

### Command Documentation Pattern
```markdown
### `cli command [options]`
Description of what it does.

**Syntax**:
```bash
cli command <required> [optional]
```

**Options**:
- `--flag`: Description

**Examples**:
```bash
# Simple
cli command file.txt

# Advanced
cli command file.txt --verbose --output=json
```
```

### Best Practices
- Document ALL public flags
- Provide `--help` and `--version`
- Show error messages and solutions
- Include exit codes table

---

## Visual Documentation

### When to Use Diagrams

**User Manuals**:
- Feature flowcharts
- System context (C4)

**How-To Guides**:
- Process flowcharts
- Decision trees

**Developer Tutorials**:
- Architecture diagrams
- Sequence diagrams (auth flows)
- Data flow diagrams

### Screenshot Guidelines
- Capture full relevant UI section
- Consistent resolution/zoom
- Add annotations (arrows, highlights)
- Alt text: `![Action description](image.png)`
- Web-friendly format (PNG, WebP)

---

## Accessibility Requirements (2025)

### WCAG Compliance
- ✅ Proper heading hierarchy (H1 → H2 → H3)
- ✅ Alt text for all images
- ✅ Color contrast (4.5:1 minimum)
- ✅ No color-only instructions
- ✅ Keyboard navigation described
- ✅ Captions for videos

### Inclusive Language
- Avoid jargon without definition
- Use simple, clear sentences
- Consider multilingual users
- Screen reader friendly

---

## Modern Approaches (2025)

### Docs as Code
- Markdown in version control
- Review process like code
- Automated testing of examples
- CI/CD for documentation

### AI Enhancement
- AI draft generation
- Automated gap detection
- Version consistency checks
- Smart search/discoverability

### Rich Media
- Video tutorials
- Interactive code sandboxes
- Live demos
- AR/VR for complex systems

---

## Quality Checklist

### All Documentation
- [ ] Clear title and description
- [ ] Version number and last updated date
- [ ] Target audience identified
- [ ] Prerequisites listed
- [ ] Verified/tested procedures
- [ ] Visual aids (diagrams/screenshots)
- [ ] No spelling/grammar errors
- [ ] Consistent formatting
- [ ] Feedback mechanism

### User-Facing Docs
- [ ] Friendly, approachable tone
- [ ] No unexplained jargon
- [ ] Common issues addressed
- [ ] Support contact info

### Developer Docs
- [ ] All code tested and working
- [ ] Complete sample project
- [ ] Common errors documented
- [ ] Links to advanced topics

---

## Common Mistakes to Avoid

❌ **Too much theory upfront**: Start with hands-on
❌ **Untested code examples**: All code must work
❌ **Missing prerequisites**: Always list requirements
❌ **No visual aids**: Screenshots essential
❌ **Outdated content**: Date last reviewed
❌ **No verification steps**: Show expected output
❌ **Assuming knowledge**: Define all terms
❌ **Poor structure**: Use clear headings
❌ **No troubleshooting**: Address common errors

---

## Performance & Usability

### Testing Your Documentation
1. **Fresh eyes test**: Have someone unfamiliar follow it
2. **Time estimate**: Actually time how long it takes
3. **Error collection**: Note every stumbling block
4. **Feedback loop**: Add FAQ based on questions

### Continuous Improvement
- Monitor analytics (where users get stuck)
- User feedback forms
- Regular review cycles (quarterly)
- Update when product changes

---

## References

**Industry Standards**:
- IEEE 830 (Software Requirements)
- OpenAPI 3.0 Specification
- WCAG 2.1 (Accessibility)

**Further Reading**:
- [Diátaxis Documentation Framework](https://diataxis.fr/)
- [Google Developer Documentation Style Guide](https://developers.google.com/style)
- [Write the Docs Community](https://www.writethedocs.org/)

---

**Apply these practices to create documentation that users actually want to read!** 📚
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: 471kUpdated Claude CodeCodexVerifiedInstall
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: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall