# implement-documentation (Unified Skill)

## Core Instructions (SKILL.md)

# Implement Documentation Topic

Write a high-signal documentation topic using the Unified Frameworks for Technical Information Architecture.

## Core Rules

- Establish context and prerequisites in the first two sentences (EPPO).
- Lead with the answer or primary assertion in the TL;DR and first paragraph (Pyramid Principle).
- Use explicit, semantic block labels (descriptive headers) for every 2-3 paragraphs (Info Mapping).
- Provide a clear "fail-state" or troubleshooting section (Minimalism).
- Do not mix intents: no deep theory in a How-to. If theory is required, use a Note or Deep Dive sidebar to maintain quadrant purity.
- Do not use "Next" or "Previous" as the only navigational cues (EPPO).

## Procedure

1. Quadrant check: identify the Diátaxis quadrant and follow its rhetorical rules. Use `references/templates.md` for the matching template (Tutorial, How-to, Reference, or Explanation). Use `references/anti-patterns.md` to avoid common failures for that quadrant.
2. EPPO initialization: every topic must stand alone. Start with a clear task- or concept-focused title and a context block ("This topic covers [X]. You should already understand [Y] and have [Z] installed.").
3. Information mapping: chunk the body into units under 7 items; label headers by result or content (e.g., "Configuring the API" not "Configuration"); convert complex comparisons or steps into tables and lists.
4. AI-first polish: ensure headers are descriptive for RAG indexing and provide a 1-2 sentence TL;DR at the top for LLM ingestion.
5. If setting up a new docs site or choosing tooling, use `references/tooling-comparison.md` for platform selection and `references/versioning.md` for versioning and changelog strategy. For a full Diátaxis rollout, use `references/diataxis-implementation.md`.

## Rules

- The canonical theory lives in `content/research-documentation-frameworks.md`; the references here are operational excerpts that link back to it.

## Related Skills

- `research-documentation` — audit before writing.
- `review-documentation` — review after writing.

---

## Reference: anti-patterns.md

# Documentation Anti-Patterns

Avoid these during Step 1 (quadrant check) and throughout writing. Source: `content/research-finding-library-docs-best-practices.md` (Section 1, Common Mistakes and Anti-Patterns).

## Leading with explanation instead of action

The engineer's impulse is to explain how a system works before showing how to use it. This is backwards for most users. Quickstart then how-to then reference is the ramp-up order. Fix: in Tutorials and How-tos, lead with a runnable result; move "how it works" to Explanation.

## One stream of text serving as THE DOCS

A single document trying to teach beginners, guide intermediate users, and serve as expert reference serves none of them. Fix: split by Diátaxis quadrant; each page has one intent.

## FAQ lists as an anti-pattern

An FAQ is "the box in the garage where you put things when you can't be bothered to put them in the right place." If information is in the right Diátaxis quadrant, it does not need repeating in an FAQ. Fix: place each answer where it belongs; delete the FAQ or keep only genuinely miscellaneous items.

## The curse of knowledge

Experts forget what it was like not to know. They skip "obvious" steps, use undefined jargon, assume context beginners lack. Fix: in Tutorials, state every prerequisite; define jargon on first use; have a non-expert read it.

## Stale documentation

Docs not embedded in the development workflow drift from the code. Incorrect docs are worse than missing docs — they waste time and erode trust. Fix: docs-as-code, docs-updated checkboxes in PRs, "you touch it, you document it."

## Knowledge silos

Scattered docs across wikis, READMEs, Confluence, Notion create a fragmented experience where users cannot find things and contributors do not know where to put new content. Fix: one canonical location, ideally in the same repo as the code.

## Partial coverage

Documenting some but not all of a feature or API creates a false sense of completeness — users assume the undocumented part does not exist or work. Fix: cover a concept fully or not at all; use the completeness checklist (in the `research-documentation` skill's `references/checklist.md`).

## Mixed-intent "Frankenbooks"

A page that starts as a tutorial, becomes reference, and ends as explanation. Fix: split into three focused pages; each keeps quadrant purity. Use a Note or Deep Dive sidebar only when a sliver of theory is required inside a task page.

---

## Reference: diataxis-implementation.md

# Diátaxis Implementation Guide

Six-step rollout for adopting Diátaxis on an existing or new documentation set. Use in Step 5 when the task is a full architecture rollout rather than a single topic. The Diátaxis framework theory is canonical in `content/research-documentation-frameworks.md`; these implementation steps are sourced from `content/research-finding-library-docs-best-practices.md` (Section 3, How to Implement Diátaxis in Practice).

## Step 1: Audit existing documentation

Catalog every existing document and classify it as Tutorial, How-to, Reference, or Explanation. The audit typically reveals that most docs are reference, with gaps in tutorials and explanation. (Use the `research-documentation` skill for this.)

## Step 2: Create a directory structure

Create four directories or sections: `tutorials/`, `how-to/` (or `guides/`), `reference/`, and `explanation/`. Apply title conventions per type: Explanation titles use "Understanding / Dive into / Introduction to..."; How-to titles start with "How to..."; Tutorial titles use "Getting started with...".

## Step 3: Assign content types and split mixed documents

Long mixed-topic documents become multiple short, focused documents. A document that is tutorial then reference then explanation becomes three separate documents, each in its quadrant directory.

## Step 4: Establish contribution guidelines

Document the framework for contributors so new docs land in the right place from the start. Without guidelines the four-directory structure fills with misclassified content. Keep the guidelines short: one sentence per quadrant on what belongs there.

## Step 5: Integrate with the development workflow

Add architecture specs to Reference alongside code changes. Add technical decision logs to Explanation during feature development. Docs-updated checkboxes in PR templates. This integration is what keeps docs current.

## Step 6: Use Diátaxis as an AI prompt template

The clear information patterns make effective AI prompt templates: ask a model to sort unstructured content into the four patterns to accelerate a first draft, then review and refine. (See `templates.md` for the per-quadrant output shapes.)

## Critiques to keep in mind

Diátaxis is a guide, not dogma. Forcing every artifact into four rigid buckets produces awkward docs. The terms overlap (tutorial vs. how-to needs editorial judgment). The framework does not address content reuse (DITA's conref may suit enterprise multi-output needs) nor finding aids. For early-stage projects, a single compelling quick start may suffice before the full suite.

---

## Reference: templates.md

# Diátaxis Templates

One template per quadrant. Match the template to the quadrant identified in Step 1. The canonical theory is `content/research-documentation-frameworks.md`.

## Tutorial (learning-oriented, beginners)

Goal: build competency through a guided, safe experience. Show, do not lecture.

```markdown
# [Getting Started with X]

**TL;DR:** [1-sentence outcome for human/AI]

## What You Will Learn
By the end you will have [concrete result]. No prior knowledge of [X] is assumed.

## Prerequisites
- [Prerequisite 1]
- [Prerequisite 2]

## Step 1: [Specific Result]
[Chunked, do-this-now instructions. Each step yields a visible result.]

## Step 2: [Specific Result]
[Chunked instructions.]

## Recap & Next Steps
You built [X]. Next, try [lateral link 1] or [lateral link 2].
```

## How-to (task-oriented, assumes baseline competence)

Goal: answer a specific question directly. Minimal theory.

```markdown
# [Task-Focused Title]

**TL;DR:** [1-sentence summary for human/AI]

## Context & Prerequisites
This guide explains how to [Goal]. Before starting, ensure you have:
- [Prerequisite 1]
- [Prerequisite 2]

## [Action Step 1: Specific Result]
[Chunked instructions]

## [Action Step 2: Specific Result]
[Chunked instructions]

## Troubleshooting: Common Fail-States
| Symptom | Cause | Fix |
| :--- | :--- | :--- |
| [Error] | [Reason] | [Solution] |

## Further Exploration
- [Lateral Link 1] (Subject affinity)
- [Lateral Link 2] (Subject affinity)
```

## Reference (information-oriented, experienced users)

Goal: fast, accurate facts. Scannable tables, no narrative filler.

```markdown
# [X] Reference

**TL;DR:** [1-sentence summary for human/AI]

## [Function/Endpoint/Class Name]

**Signature:** `signature`

**Parameters:**
| Name | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| [name] | [type] | yes/no | [description] |

**Returns:** [type and meaning]

**Errors:**
| Code | Meaning | Remediation |
| :--- | :--- | :--- |
| [code] | [meaning] | [fix] |

**Example:**
[Minimal, complete, runnable example]
```

## Explanation (understanding-oriented, the "why")

Goal: deepen knowledge; no specific task. Discussion, design rationale, trade-offs.

```markdown
# [Understanding X]

**TL;DR:** [1-sentence summary for human/AI]

## Why [X] Exists This Way
[Design rationale and history. No steps.]

## Key Concepts
- [Concept 1]: [definition and why it matters]
- [Concept 2]: [definition and how it relates to Concept 1]

## Trade-offs
| Approach | Pro | Con |
| :--- | :--- | :--- |
| [A] | [pro] | [con] |
| [B] | [pro] | [con] |

## Further Exploration
- [Lateral Link 1] (Subject affinity)
- [Lateral Link 2] (Subject affinity)
```

---

## Reference: tooling-comparison.md

# Tooling Comparison & Docs-as-Code

Use in Step 5 when choosing a platform or setting up docs infrastructure. Platform selection is an implementation decision, not an audit finding. Source: `content/research-finding-library-docs-best-practices.md` (Section 6, Modern Tooling and Infrastructure).

## Platform comparison

| Platform | Best For | Stack | Key Strength |
| :--- | :--- | :--- | :--- |
| Docusaurus | Complex OSS docs, versioning | React/JS | Ecosystem, versioning, MDX |
| MkDocs (Material) | Python projects, simple setup | Python | Simplicity, polished theme |
| Sphinx | Python API reference | Python | Autodoc, multiple outputs |
| Read the Docs | OSS hosting, versioning | Agnostic | Free hosting, versioning |
| GitBook | Team knowledge bases | Agnostic | Editing UX, AI search |
| Mintlify | API docs, dev portals | Agnostic | Design, AI search, OpenAPI |
| Starlight | Performance-critical docs | Astro | Performance, accessibility |
| Nextra | Custom Next.js sites | React/Next.js | Customization, React components |

## How to choose

- Python ecosystem or simplicity: MkDocs / Sphinx.
- API reference that must stay synced to code: Sphinx autodoc, mkdocstrings, or TypeDoc.
- API docs with interactive playground: Mintlify.
- Complex OSS docs with versioning and i18n: Docusaurus.
- Performance and built-in accessibility: Starlight.
- Free open-source hosting with versioning: Read the Docs.

## Docs-as-code workflow

Write docs in plain text (Markdown/AsciiDoc/reST), store in Git, review through pull requests, publish through CI/CD. Core practices:

- Store docs in the same repository as the code.
- Write in plain text (Markdown dominates for developer docs).
- Review all doc changes through the same PR process as code.
- Automate builds and deployments via CI/CD (GitHub Actions, GitLab CI).
- Enforce quality through automation: Vale, markdownlint, link checkers (htmlproofer, lychee), spell checkers on every PR.
- Generate API reference from OpenAPI/Swagger to keep it synchronized.

## Specification-driven API docs

- **OpenAPI** is the standard for REST APIs (YAML/JSON). Use it to auto-generate interactive reference (Swagger UI, Redoc, Stoplight Elements), client SDKs, and mock servers, and to power AI agent tool manifests.
- **AsyncAPI** extends the approach to event-driven APIs (WebSockets, Kafka, MQTT).
- Prefer a **design-first** approach: write the spec before the code. This enables early collaboration, immediate mock servers, and ensures docs are never an afterthought.

## Interactive documentation

Place the interactive element directly adjacent to the relevant docs, not on a separate playground page. Live code playgrounds (CodeSandbox, StackBlitz), interactive API explorers (Swagger UI, Mintlify), and embedded REPLs reduce time-to-first-success.

---

## Reference: versioning.md

# Versioning & Changelog Strategy

Use in Step 5 when setting up versioned documentation. Source: `content/research-finding-library-docs-best-practices.md` (Section 2, Versioned Documentation Strategies).

## Version-tagged documentation

Each major release should have a corresponding docs version. Tools like Read the Docs, Docusaurus, and Sphinx provide built-in versioned docs so users can select the version matching their installed software.

## Version selector in the UI

A prominent version selector in navigation lets users switch versions. The current stable version is the default, with clear indicators when a user is viewing an older or pre-release version.

## Deprecation notices

When features are deprecated, update docs immediately with a deprecation notice, the version in which deprecation occurred, and a migration path to the replacement.

## Changelog as a first-class document

Treat the changelog as a primary artifact, not an afterthought. Link it prominently from the docs home page and update it as part of the release process. Link migration guides from the changelog entries that introduce breaking changes; highlight breaking changes prominently.

## Write version-agnostic content where possible

Conceptual and explanation content that does not change between versions should avoid version-specific references. This reduces maintenance burden and prevents confusion.

## Docs-as-code for version control

Store docs in the same Git repository as the code (or a closely linked one) so docs version alongside code. Pull requests for code changes include doc updates; CI/CD pipelines can enforce that docs are updated before a release merges.

## Canonical URLs

Versioned docs create a risk of duplicate-content search penalties. Use canonical URL tags pointing search engines to the current stable version of each page.

---