Product Documentation Skill

Step 2 — Identify the Audience

Who will read this?
├── Developers / Engineers      → Technical depth, code examples, precise terminology
├── End Users (non-technical)   → Plain language, task-focused, screenshots/visuals
├── Admins / DevOps             → Config-heavy, command-line, system specifics
├── Business Stakeholders       → High-level, outcome-focused, no jargon
├── Internal Team               → Context-rich, process-specific, searchable
└── Mixed / Public              → Layer: summary + depth; progressive disclosure

Step 3 — Apply the DITA Content Model

Structure every piece of documentation as one of these types:

Core Documentation Principles

1. The Four Properties of Great Docs

ACCURATE    → Technically correct. Tested. Never guessed.
COMPLETE    → Covers what users need. No critical gaps.
CLEAR       → One meaning per sentence. No ambiguity.
MAINTAINED  → Versioned, dated, owner-assigned. Doesn't rot.

2. The Divio Documentation System

Every docs site needs all four quadrants:

                LEARNING-ORIENTED        PROBLEM-ORIENTED
               ┌────────────────────────┬───────────────────────┐
PRACTICAL      │  TUTORIALS             │  HOW-TO GUIDES        │
               │  (teach by doing)      │  (solve a problem)    │
               ├────────────────────────┼───────────────────────┤
THEORETICAL    │  EXPLANATION           │  REFERENCE            │
               │  (understand why)      │  (information lookup) │
               └────────────────────────┴───────────────────────┘

Source: Daniele Procida, Divio Documentation System

3. Progressive Disclosure

Never dump everything at once. Layer information:

Level 1 → What is this? One sentence answer.
Level 2 → How do I get started? 5-minute quickstart.
Level 3 → How do I do [specific task]? Task guides.
Level 4 → What are all the options? Full reference.
Level 5 → Why was it designed this way? Conceptual explanation.

4. Every Doc Page Has One Job

If you can't state the single purpose of a page in one sentence, split it into two pages.

Writing Standards

Voice & Tone

• Active voice: "Click Save" not "The save button should be clicked"
• Second person: "You can configure..." not "The user can configure..."
• Present tense: "Returns a list of users" not "Will return a list of users"
• Direct: "Set the timeout to 30 seconds" not "It may be necessary to consider setting the timeout"
• Precise: Name things exactly. If the button is called "Create Project", say "Click Create Project" not "Click the create button"

Formatting Rules

Code blocks   → ALL commands, file paths, variable names, values, JSON
Bold          → UI elements, key terms on first use, warnings
Italics       → Book titles, technical terms being defined
Tables        → 3+ items with attributes to compare
Numbered list → Sequential steps where order matters
Bullet list   → Non-sequential items, features, options
Callout boxes → Notes, warnings, tips, important notices

Callout Types

📘 NOTE      → Additional context, clarification, edge cases
⚠️ WARNING   → Actions that could cause data loss or breakage
💡 TIP       → Optional shortcuts or best practices
❗ IMPORTANT → Required steps often missed; version requirements
🚫 CAUTION   → Destructive or irreversible actions

Code Example Standards

Every code example must be:

• Complete: Runnable as-is, not pseudo-code (unless labelled)
• Minimal: No irrelevant lines
• Annotated: Comments on non-obvious lines
• Real: Use realistic values, not foo, bar, test123
• Multi-language: Show the 2–3 most common languages for the audience when relevant

Page Templates (Quick Reference)

API Endpoint Page

## [HTTP Method] /path/to/endpoint
[One sentence: what this endpoint does]

### Request
**Headers**
| Header | Required | Description |
**Parameters / Body**
| Field | Type | Required | Description |

### Response
[Status code and description]
[Response schema table]

### Code Examples
```[language]
[Complete working example]

Error Codes

| Code | Meaning | How to Fix |

### Getting Started Guide

Getting Started with [Product]

[What users will accomplish by the end] [Time estimate: X minutes]

Prerequisites

• [Requirement 1]
• [Requirement 2]

Step 1: [Install / Set Up]

Step 2: [Configure]

Step 3: [First Action]

Step 4: [Verify It Works]

Next Steps

• [Related guide 1]
• [Related guide 2]

### Troubleshooting Entry

[Error message or symptom exactly as user sees it]

Cause: [Why this happens] Solution:

1. [Step]
2. [Step] If this doesn't work: [Escalation path]

---

## Documentation Quality Checklist

Before marking any documentation complete:

**Content**
- [ ] Every claim is accurate and tested
- [ ] No content assumes knowledge not introduced earlier
- [ ] All code examples are runnable and correct
- [ ] Prerequisites are listed upfront
- [ ] Expected output / result is shown after each step

**Structure**
- [ ] Page has a clear single purpose
- [ ] H1 title states exactly what the page covers
- [ ] Logical flow: overview → steps → reference → troubleshooting
- [ ] Scannable: headings, bullets, tables where appropriate

**Language**
- [ ] Active voice throughout
- [ ] No jargon without definition
- [ ] Consistent terminology (one name per concept throughout)
- [ ] Callouts used for warnings and important notes

**Metadata**
- [ ] Last updated date
- [ ] Version/product version (if applicable)
- [ ] Owner / maintainer noted
- [ ] Related pages linked

---

## Reference Files — Load When Needed

| File | Load When |
|------|-----------|
| `references/api-sdk-docs.md` | API reference, endpoint docs, SDK guides, OpenAPI, developer quickstarts |
| `references/user-product-docs.md` | User manuals, onboarding, feature guides, help center articles, FAQs |
| `references/internal-engineering-docs.md` | Runbooks, playbooks, ADRs, postmortems, SOPs, onboarding wikis |
| `references/readme-opensource.md` | README files, CONTRIBUTING guides, open source project documentation |
| `references/release-changelog.md` | Release notes, changelogs, version histories, migration guides |
| `references/architecture-design-docs.md` | System design docs, technical specs, PRDs, RFCs, architecture decision records |
| `references/docs-site-structure.md` | Documentation site IA, navigation, Docusaurus/Mintlify/GitBook setup |
| `references/writing-style-guide.md` | Terminology, voice, tone, formatting rules, accessibility standards |
| `references/docs-templates.md` | Full copy-paste templates for every doc type |