Technical Writer
Generate product documentation by analyzing codebases and translating technical implementation into clear, structured user guides.
Before Starting
Step 0: Product Context
Check for .agents/mkt/product-context.md. If available, read for product context to inform documentation.
Required Artifacts
None — scans project structure directly.
Optional Artifacts
| Artifact | Source | Benefit |
|---|---|---|
product-context.md | mkt-copywriting | Product context for documentation |
Workflow
- Scan project structure to understand architecture
- Identify key files for analysis
- Extract core concepts from implementation
- Generate documentation following the output template
Step 1: Scan Project Structure
Run a directory scan to map the project:
find . -type f \( -name "*.js" -o -name "*.ts" -o -name "*.tsx" -o -name "*.jsx" -o -name "*.py" -o -name "*.go" -o -name "*.rs" -o -name "*.swift" -o -name "*.kt" \) | head -100Also check for:
package.json,requirements.txt,Cargo.toml,go.modfor dependenciesREADME.mdfor existing context- Config files like
.env.example,config/,settings/
Step 2: Identify Key Files
Priority files to analyze:
| File Type | What It Reveals |
|---|---|
Entry points (main.*, index.*, app.*) | Core app initialization and structure |
| Route definitions | Available features and user flows |
| Components/Views | UI structure and user interactions |
| Models/Types | Core data entities and relationships |
| API handlers | Backend capabilities |
| Config/env | Environment requirements and settings |
Read 5-10 most important files. Skip generated files, node_modules, vendor directories, and test files unless specifically relevant.
Step 3: Extract Core Concepts
While reading code, identify:
Product Identity
- What problem does this solve?
- Who is the target user?
- What's the core value proposition?
Features & Capabilities
- Main user-facing features
- Key workflows and user journeys
- Input/output patterns
Architecture Decisions
- Why was this tech stack chosen?
- What design patterns are used?
- What are the dependencies?
UX Intent
- How should users navigate?
- What's the intended user experience?
- What states and feedback exist?
Step 4: Generate Documentation
Output documentation following the structure in references/doc-template.md.
Key principles:
- Write for users who have never seen the code
- Explain the "why" before the "how"
- Use concrete examples over abstract descriptions
- Include screenshots or diagrams when describing UI flows
- Keep technical jargon to a minimum
Output Format
When saving documentation artifacts, use this frontmatter:
---
skill: mkt-technical-writer
version: 1
date: [today's date]
status: draft
---On re-run: rename existing artifact to [name].v[N].md and create new with incremented version.Generate a single markdown file with all documentation. See references/doc-template.md for the full structure.
If the project is large, suggest breaking into multiple focused guides:
- Getting Started Guide
- Feature Reference
- User Workflows
- Configuration Guide