tomevault-io Doc Writer Skill
Create or update technical documentation that is clear, consistent, and maintainable.
When to Use
- Creating new documentation
- Updating existing docs
- Writing README files
- Documenting architecture decisions (ADRs)
- Creating API documentation
Do NOT use when:
- Just fixing typos (edit directly)
- Writing code comments (do inline)
- Creating one-off notes (use session logs)
Inputs
Required
- Document type: README, ADR, API docs, etc.
- Audience: Who will read this?
- Purpose: What should they learn/do?
Optional
- Related docs: Links to existing documentation
- Examples: Code samples to include
- Diagrams: Visual aids needed
Steps
Step 1: Determine Document Type
What to do: Choose the appropriate template and location.
Document Types:
| Type | Location | Purpose |
|---|---|---|
| README | Project/component root | Overview and quickstart |
| ADR | docs/architecture/adr/ |
Architecture decisions |
| API Doc | docs/api/ |
Endpoint documentation |
| Guide | docs/guides/ |
How-to instructions |
| Knowledge Base | docs/knowledge_base.md |
Patterns and gotchas |
| Project Brief | docs/project_brief.md |
Project overview |
| Implementation Schedule | docs/implementation_schedule.md |
Task tracking |
Step 2: Apply Template
What to do: Use the appropriate template for consistency.
README Template:
# Project/Component Name
> One-line description
## Overview
Brief description of what this is and why it exists.
## Quick Start
### Prerequisites
- Requirement 1
- Requirement 2
### Installation
```bash
# Installation commands
Usage
# Basic usage
Documentation
- Link to detailed docs
- API Reference
Contributing
See CONTRIBUTING.md
License
License Type
**ADR Template:**
```markdown
# ADR-XXX: Title
## Status
- Proposed / Accepted / Deprecated / Superseded by ADR-YYY
## Context
What is the issue that we're seeing that is motivating this decision?
## Decision
What is the change that we're proposing or have agreed to implement?
## Consequences
What becomes easier or more difficult to do?
### Positive
- Benefit 1
- Benefit 2
### Negative
- Drawback 1
- Drawback 2
## Alternatives Considered
### Alternative 1: Name
Description and why it was rejected.
### Alternative 2: Name
Description and why it was rejected.
## References
- [Link 1]()
- [Link 2]()
Guide Template:
# Guide: Topic
## Overview
What this guide covers and who it's for.
## Prerequisites
What you need before starting.
## Steps
### Step 1: Title
Description and commands.
### Step 2: Title
Description and commands.
## Verification
How to verify it worked.
## Troubleshooting
Common issues and solutions.
## Next Steps
Where to go from here.
Step 3: Write Content
What to do: Write clear, concise content following standards.
Writing Standards:
- Clear Headings: Use descriptive headings (not just "Overview")
- Short Paragraphs: 2-3 sentences max per paragraph
- Bullet Points: Use lists for multiple items
- Code Blocks: Use fenced code blocks with language tags
- Links: Use relative links to other docs
- Examples: Include concrete examples
Example - Good vs Bad:
Bad:
This function does stuff with data.
Good:
The `process_data()` function validates and transforms raw data:
- **Validates**: Checks required fields and data types
- **Transforms**: Converts dates to ISO format
- **Returns**: Cleaned data dictionary
Example:
```python
result = process_data({"date": "01/01/2026", "value": 100})
# Returns: {"date": "2026-01-01", "value": 100}
### Step 4: Add Cross-References
**What to do:**
Link to related documentation.
**Pattern:**
```markdown
See also:
- [Database Schema](database_schema.md) for table definitions
- [API Reference](../api/endpoints.md) for usage examples
- [Related ADR](../adr/adr-001-database-choice.md) for context
Step 5: Review and Update
What to do: Review for completeness and update related docs.
Review Checklist:
- All sections filled
- Links work
- Code examples tested
- No typos
- Consistent with other docs
Update Related Docs:
- Update table of contents if exists
- Add link from overview docs
- Update implementation schedule if applicable
Validation
Success Criteria
- Follows appropriate template
- All sections complete
- Links to related docs
- Code examples tested
- Audience-appropriate level
- Consistent terminology
Verification
# Check links
python scripts/check_links.py
# Preview markdown
cat docs/your_file.md | less
# Build docs site (if using mkdocs)
mkdocs serve
Rollback
If Documentation is Wrong
- Create correction task in implementation schedule
- Update document with correct info
- Note correction in session log
- Notify team if others reference the doc
Common Mistakes
- No audience consideration: Write for your reader
- Outdated code examples: Always test examples
- Missing context: Explain why, not just what
- Wall of text: Use formatting to break up content
- Broken links: Check all links before committing
- Inconsistent terms: Use glossary terms consistently
Related Skills
- Test Writer: For documenting test patterns
- API Endpoint: For API documentation
- Start Session: For session log documentation
Links
- Context:
.agent/CONTEXT.md - Agent Guidance:
.agent/AGENTS.md - Documentation Guide:
docs/documentation_guide.md - Glossary:
docs/glossary.md
Examples
Example 1: Architecture Decision Record
Scenario: Documenting choice of PostgreSQL over MongoDB.
Key Sections:
- Context: Need ACID transactions and complex queries
- Decision: Use PostgreSQL with SQLAlchemy ORM
- Consequences: Better consistency, need migration system
Example 2: API Endpoint Documentation
Scenario: Documenting new user authentication endpoint.
Content:
- Endpoint URL and method
- Request/response schemas
- Error codes and examples
- Authentication requirements
Remember: Good documentation saves time for everyone!
Converted and distributed by TomeVault — claim your Tome and manage your conversions.