documentation-writing

Documentation Writing — Project Documentation Engine (s34)

Purpose

Generate clear, accurate, audience-appropriate documentation that makes a project understandable and usable by every stakeholder — from backend engineers reviewing architecture to first-time users trying to get started. Every document follows the principle: the reader should never have to guess.

---

Prerequisites

• Project artifacts available (PRD, pipeline YAML, experiment results, etc.)
• Target audience identified (engineers, non-technical users, SREs)
• No specific skill outputs required — can be invoked at any phase
• Access to project repository for documentation rendering

Input Contract

Input	Source	Required
Project codebase / structure	Repository exploration	Yes
Target documentation type	User prompt (technical / userflow / usage / README)	Yes
Target audience	User prompt or inferred	Yes
PRD / specifications	s01 output	No
ADRs	s01 output	No
Existing documentation	docs/ directory scan	No
User's tone preference	s02 taste file	No

Output Contract

Output	Destination	Format
Documentation artifact	docs/<type>/ or project root	Markdown
README.md	Project root	Markdown with badges, TOC, sections
User flow diagram	docs/userflows/	Mermaid flowchart or numbered steps
Technical spec	docs/technical/	Markdown with code blocks, diagrams
Usage guide	docs/guides/	Markdown with screenshots, plain language

---

Documentation Types

Type 1: Technical Documentation

Audience: Engineers, SREs, DevOps, platform teams

Structure:

# <Component/Feature Name> — Technical Specification

## Overview
One paragraph: what it does, why it exists, what problem it solves.

## Architecture
High-level design. Mermaid diagrams for data flow, component relationships.

## Data Model
Tables, schemas, relationships. Include field types, constraints, defaults.

## API Reference
Endpoint, method, request/response schema, error codes, rate limits.

## Configuration
Environment variables, config files, feature flags. Include defaults.

## Error Handling
Error codes, retry logic, fallback behavior.

## Dependencies
External services, libraries, infrastructure requirements.

## Security Considerations
Auth requirements, data sensitivity, threat model.

## Testing
How to test locally, integration test setup, mocking external deps.