# Documentation Writing

> >

- **Type:** Skill
- **Install:** `agentstack add skill-dungnotnull-hybrid-harness-chaos-process-prm-s34-documentation-writing`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [dungnotnull](https://agentstack.voostack.com/s/dungnotnull)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [dungnotnull](https://github.com/dungnotnull)
- **Source:** https://github.com/dungnotnull/hybrid-harness-chaos-process-prm/tree/main/skills/s34-documentation-writing

## Install

```sh
agentstack add skill-dungnotnull-hybrid-harness-chaos-process-prm-s34-documentation-writing
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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//` 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**:
```markdown
#  — 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.
```

**Rules**:
- Use Mermaid diagrams for architecture and data flow
- Include runnable code examples (not pseudocode)
- Document error states as thoroughly as happy paths
- Link to ADRs for design decisions
- Every config option must show its default value

---

### Type 2: User Flow Documentation

**Audience**: Product managers, designers, QA, engineers

**Structure**:
```markdown
#  — User Flow

## Overview
What the user is trying to accomplish. Entry points.

## Flow Diagram
Mermaid flowchart or numbered step sequence.

## Happy Path
Step-by-step with expected outcomes at each step.

## Decision Points
Branching logic with conditions and outcomes.

## Error States
What happens when things go wrong. Recovery paths.

## Edge Cases
Unusual but valid scenarios and how they're handled.

## Related Flows
Links to adjacent or dependent flows.
```

**Rules**:
- Always include a visual flow diagram (Mermaid preferred)
- Number every step
- Decision points must have explicit conditions ("If X > threshold...")
- Error states must include the user-visible message and recovery action
- Keep to one primary flow per document; split sub-flows into linked docs

---

### Type 3: Usage Instructions (Non-Technical)

**Audience**: End users, business stakeholders, customer support, new team members

**Structure**:
```markdown
# How to  — Usage Guide

## What You'll Learn
One sentence: what the reader will be able to do after reading.

## Before You Start
Prerequisites, required access, accounts, or setup steps.

## Step-by-Step Instructions
1. **Do this first** — Plain language explanation.
   - What you'll see: description of expected result.
2. **Then do this** — ...
   - What you'll see: ...

## Common Questions
**Q: What if I see X?**
A: Do Y.

## Need More Help?
Link to support, contact info, or escalation path.
```

**Rules**:
- Write at a 6th-grade reading level
- Use "you" language ("Click the button" not "The user clicks")
- Every step must describe what the user will see after performing it
- Include screenshots or image references where helpful (using ``)
- No jargon without inline explanation
- Bold the action verb at the start of each step
- Provide a "Common Questions" section for the top 3-5 likely issues
- Use numbered lists for sequential steps, bullets for options

---

### Type 4: README Documentation

**Audience**: Everyone — developers, users, contributors, evaluators

**Structure**:
```markdown
# Project Name

One-line description with key value proposition.

[badges]

## What Is This?
2-3 sentences. Who it's for, what it does, why it exists.

## Quick Start
Minimum steps to get running. Copy-pasteable.

## Features
Bullet list of key capabilities. Link to detailed docs.

## Installation
All supported methods (npm, pip, docker, source).

## Usage
Most common use case with code example.

## Configuration
Key options in a table.

## Contributing
How to contribute. Link to CONTRIBUTING.md if exists.

## License
License type + link.

## Acknowledgments
Credits, inspirations, dependencies.
```

**Rules**:
- The first 5 lines must answer: What is this? Who is it for? Why should I care?
- Quick Start must be copy-pasteable and work on a fresh machine
- Badge links must be valid
- Keep it under 500 lines — link to detailed docs for depth
- Include a table of contents if >100 lines
- Show, don't tell — one code example is worth 10 paragraphs
- Match the project's existing badge style

---

## Workflow

```
Step 1:  DETERMINE documentation type from user request
Step 2:  SCAN the codebase / existing docs for context
Step 3:  IDENTIFY target audience
Step 4:  LOAD taste preferences (tone, style, language)
Step 5:  SELECT the appropriate template from above
Step 6:  RESEARCH the codebase thoroughly — read source files,
         configs, tests, existing docs. Never guess.
Step 7:  DRAFT the documentation following the template
Step 8:  VALIDATE accuracy:
         - Every code example must be runnable
         - Every file path must exist
         - Every config option must be verified in source
         - Every link must resolve
Step 9:  REVIEW readability:
         - Technical docs: can an engineer understand without asking questions?
         - User flows: can QA write test cases from this alone?
         - Usage guides: can a non-technical person follow without help?
         - README: does a first-time visitor understand the project in 30 seconds?
Step 10: WRITE to the appropriate location
Step 11: UPDATE README.md if the new doc should be linked
```

---

## AI Agent Integration

### Autonomy Level

| Aspect | Level | Description |
|---|---|---|
| Current | L1 | AI generates documentation drafts; human reviews and edits |
| Target | L2 | AI produces publication-ready documentation with minimal human editing |

### Harness AI Agent

**Agent**: None (documentation by design)
**Capabilities**:
- Technical specification generation
- API documentation generation
- Mermaid diagram generation for user flows
- README generation
- Audience-aware writing style adaptation

### Human Gates

- Documentation accuracy review before publishing
- Technical review for correctness
- Style and tone approval

## Success Criteria

- [ ] Documentation type matches user request
- [ ] Target audience is explicitly identified
- [ ] Template structure followed
- [ ] All code examples are tested/runnable
- [ ] All file paths and links are verified
- [ ] Reading level matches audience (technical = expert, usage = beginner)
- [ ] Diagrams included where structure or flow is described
- [ ] Document is discoverable (linked from README or docs index)
- [ ] No placeholder text ("TODO", "TBD", "lorem ipsum")
- [ ] Spell-checked and grammar-checked

---

## Examples

### Example: Technical Doc Generation

```
User: "Write technical documentation for the authentication module"

Agent:
1. Scans src/auth/, reads all files
2. Identifies JWT flow, OAuth providers, middleware chain
3. Generates docs/technical/authentication.md with:
   - Architecture diagram (Mermaid)
   - Token lifecycle diagram
   - API endpoint reference table
   - Configuration options table
   - Error code reference
4. Links from README.md
```

### Example: Usage Guide Generation

```
User: "Create a beginner guide for setting up the project"

Agent:
1. Reads README.md, package.json / pyproject.toml, config files
2. Identifies prerequisites (Node.js, Docker, etc.)
3. Generates docs/guides/getting-started.md with:
   - "What You'll Learn" section
   - Prerequisites checklist
   - Step-by-step install with expected outputs
   - "Common Questions" for top issues
4. Links from README.md Quick Start section
```

### Example: README Generation

```
User: "Generate a README for this project"

Agent:
1. Scans entire project structure
2. Reads package.json / pyproject.toml for metadata
3. Identifies key features from source code
4. Generates README.md with:
   - Project name and one-liner
   - Badges (license, version, CI status)
   - Quick Start (copy-pasteable)
   - Features list with doc links
   - Installation methods
   - Usage example
   - Contributing guide
   - License
```

---

*This skill is callable at any phase. It produces documentation artifacts only — no code changes, no configuration, no infrastructure.*

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [dungnotnull](https://github.com/dungnotnull)
- **Source:** [dungnotnull/hybrid-harness-chaos-process-prm](https://github.com/dungnotnull/hybrid-harness-chaos-process-prm)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-dungnotnull-hybrid-harness-chaos-process-prm-s34-documentation-writing
- Seller: https://agentstack.voostack.com/s/dungnotnull
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.