# documentation (Unified Skill) ## Core Instructions (SKILL.md) #### Core Instructions (content/distilled/documentation/SKILL.md) # Documentation Router Route documentation work to the right mode, then read that mode's instructions before acting. ## Modes | Task signal | Mode | Read | |---|---|---| | audit existing docs or plan a new documentation suite | research-documentation | `references/research-documentation/SKILL.md` | | write documentation using Diátaxis, Info Mapping, EPPO principles | implement-documentation | `references/implement-documentation/SKILL.md` | | review docs for cognitive scannability and AI-readiness | review-documentation | `references/review-documentation/SKILL.md` | ## Selection rules - No docs or restructuring from scratch → **research-documentation** first; its report feeds implementation. - Writing or rewriting content → **implement-documentation**. Judging existing content quality → **review-documentation**. - Broken links or link-text/target mismatches are the complaint → use the `doc-link-verifier` skill instead; this router is about architecture and content quality. ## Procedure 1. Identify the mode from the table above. 2. Read the referenced file (resolve paths against this skill's directory); follow its checklists, templates, and report formats. --- #### Reference: references/implement-documentation/references/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: references/implement-documentation/references/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: references/implement-documentation/references/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: references/implement-documentation/references/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: references/implement-documentation/references/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. --- #### Reference: references/implement-documentation/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: references/research-documentation/references/checklist.md # Documentation Completeness Checklist Use during the audit (Step 2) to check existing or planned coverage. Source: `content/research-finding-library-docs-best-practices.md` (Section 1, the best-practices checklist, and Section 5, accessibility). ## Completeness and accuracy - All public APIs, endpoints, parameters, and return values are documented. - All error codes and messages are documented with explanations and remediation steps. - Prerequisites and system requirements are stated upfront. - All code examples are tested and verified to work with the current version. - No documented features are missing from the implementation, and no undocumented features exist. ## Getting started and onboarding - A "Getting Started" or "Quick Start" guide exists and can be completed in under 15 minutes. - The guide leads to a meaningful, working result (not just "Hello, World" unless that is genuinely useful). - Installation instructions cover all supported platforms and package managers. - Authentication and configuration are explained before any API calls are shown. ## API reference - Each endpoint/function/method has a human-friendly description, not just a parameter list. - Request and response examples are provided for every endpoint. - Authentication requirements are documented per endpoint where relevant. - Rate limits, pagination, and other operational constraints are documented. - The reference is generated from or synchronized with a machine-readable specification (OpenAPI, TypeDoc, JSDoc, Sphinx autodoc). ## Versioning and changelog - Documentation is versioned to match software releases. - A changelog exists and is kept up to date. - Breaking changes are prominently highlighted. - Deprecated features are marked with migration paths provided. - Old versions of documentation remain accessible. ## Code examples - Examples exist for all major use cases. - Examples are provided in all officially supported languages/frameworks. - Examples are complete and runnable, not pseudocode or partial snippets. - Examples follow current best practices and idioms for each language. ## Conceptual and explanatory content - Architecture and design decisions are explained (the "why", not just the "what"). - Key concepts are defined before they are used. - Diagrams and visuals are used where they clarify complex relationships. ## Accessibility (WCAG 2.1 AA) - Code syntax highlighting meets minimum contrast ratios. - All navigation, search, and interactive elements are operable by keyboard alone. - Code blocks, tables, and diagrams have appropriate ARIA labels and alt text. - The site is readable on mobile and manages focus correctly in single-page-app navigation. ## Out of scope for this checklist Internationalization/localization and interactive documentation (live playgrounds, API explorers) are valid concerns but are tracked separately as platform/infrastructure decisions, not architectural-audit items. --- #### Reference: references/research-documentation/references/llm-readiness.md # LLM & Agentic Readiness Reference Operational excerpt for the AI-readiness gap assessment in Step 4. The canonical theory is `content/research-documentation-frameworks.md` (section "Machine Readability"); this file distills the concrete checks. ## `llms.txt` standard An emerging convention analogous to `robots.txt`: a machine-readable index at the docs site root that tells LLMs which pages matter most, with structured summaries. Check: - Is a `llms.txt` present at the documentation root? - Does it list the most authoritative pages (quick start, API reference, key how-tos)? - Are summaries concise and current with the latest version? ## RAG-friendly chunking Documentation structured as single-topic, self-contained modules chunks cleanly for retrieval-augmented generation. Check: - Does each page cover one well-defined topic (Diátaxis quadrant purity enables this)? - Are pages small enough to be one RAG chunk, or do they need explicit section anchors? - Is there redundant cross-page duplication that would pollute retrieval? ## MCP and agent manifests For tooling/agent documentation, the description fields are documentation. Check: - Are MCP tool manifests present with precise `name`, `description`, input/output JSON schemas? - Are plugin/agent cards machine-readable with capability boundaries and error conditions? - Is language precise enough for a machine (no context-dependent ambiguity a human would resolve but an agent would not)? ## Dual-audience design Modern docs serve human readers and machine consumers. The practices that serve both: clear structure, consistent terminology, modular organization, explicit metadata. Check: - Are headings semantic and unique (not generic "Overview" repeated across pages)? - Is front matter present (title, description, version, category)? - Are API references generated from or synchronized with a machine-readable spec (OpenAPI, AsyncAPI, JSDoc/TypeDoc, Sphinx autodoc)? ## Docs-as-context Documentation is increasingly a runtime input to AI systems (system-prompt embedding, RAG retrieval, vector search). Check: - Is clean, navigation-chrome-free text available for context-window injection? - Are code examples complete and runnable (agents execute what they read)? - Is terminology consistent so a model trained on the docs retrieves accurately? --- #### Reference: references/research-documentation/references/metrics.md # Documentation Quality Metrics Use in Step 4 to recommend measurement signals. The single most important metric is time-to-first-success; the rest build the feedback loops that keep docs honest. Source: `content/research-finding-library-docs-best-practices.md` (Section 7, Measuring Documentation Quality). ## Key metrics - **Time-to-first-success (TTFS).** Time from a developer's first encounter with the docs to their first successful use of the library/API. Measure via user testing, analytics (first page view to first successful API call), or surveys. This is the headline number. - **Support ticket deflection.** Percentage of support questions answered by docs rather than a human. Quantifies economic value; track the ratio of tickets to page views, or add "Did this page answer your question?" widgets. - **Page engagement.** Time on page, scroll depth, return visits. High bounce on getting-started may mean unmet expectations; low time on reference may mean fast finds (good) or frustration (context matters). - **Search analytics.** Track queries, click-through rates, and "no results" queries. No-results queries are direct evidence of missing docs. High click-through to a page means it is well-titled and relevant. - **Broken link rates.** Percentage of internal/external links returning 404. Automated link checking should run on every deployment (see `doc-link-verifier` skill). - **Documentation coverage.** Percentage of public APIs/endpoints/features that have docs. Measurable automatically for API reference (OpenAPI vs. documented endpoints) and code docs (docstring coverage via `interrogate`). - **Page freshness.** Age of a doc page relative to the last code change that touched the documented feature. Stale docs are a leading frustration indicator. ## User testing and feedback loops - **Usability testing.** Watch representative users attempt tasks using only the docs. Even informal tests reveal problems invisible to authors. - **Inline feedback widgets.** "Was this page helpful?" at the bottom of pages. Act on it: low-rated pages get prioritized. - **GitHub issues and discussions.** Questions already answered in docs indicate the docs are not discoverable or clear enough. - **Developer surveys.** Periodic structured feedback on quality, gaps, and priorities. - **Community channels.** Repeated questions in Discord/Slack/Stack Overflow are strong gap signals. ## Automated quality tools (CI/CD) - **Vale** — prose linter enforcing style-guide rules (passive voice, jargon, inconsistent terminology). - **markdownlint** — Markdown formatting consistency. - **htmlproofer / lychee** — internal and external link checking on every deployment. - **interrogate** (Python) — docstring coverage reporting. - **cspell / aspell** — spell checking. - **Lighthouse** — page performance, accessibility, SEO, best practices in CI. A practical pipeline: on every PR run markdownlint + Vale + cspell + example tests; on every deployment run link checking + Lighthouse; weekly run a full broken-link crawl, coverage report, and freshness report; monthly review user feedback and search analytics. ## Building a quality culture Metrics are necessary but not sufficient. Culture is the larger factor: - Add "docs updated" checkboxes to PR templates. - Allocate explicit sprint time (15-20%) to documentation and refactoring. - Apply "you touch it, you document it" — the author of a code change owns the doc update. - Assign a named owner to every documentation section. - Celebrate documentation contributions the same way as code contributions. --- #### Reference: references/research-documentation/references/report-template.md # Documentation Research Report Template Output structure for the final report (Step 5). Keep the section order stable so reports can be compared across projects. ```markdown # Documentation Research: [Project Name] ## 1. Executive Summary & Core Assertion **Core Assertion:** [The one-sentence hook] **Status:** [Summary of current architecture health] ## 2. Diátaxis Matrix | Quadrant | Existing Topics | Proposed/Missing Topics | | :--- | :--- | :--- | | **Tutorial** | | | | **How-to** | | | | **Reference** | | | | **Explanation** | | | ## 3. Snowflake Structural Map - **Macro-Journey:** [Description] - **Key Components:** [List] ## 4. EPPO & Cognitive Audit - **Frankenbooks Found:** [List of files with mixed intent] - **Context Gaps:** [Topics needing better orientation] ## 5. AI-Readiness Assessment - [ ] `llms.txt` present? - [ ] Explicit semantic labeling for RAG? - [ ] MCP/agent manifests identified? ## 6. Measurement Signals - [ ] TTFS measurable today? - [ ] Search analytics available? - [ ] Coverage / freshness tracked? ## 7. Recommended Next Steps 1. [Actionable structural change] 2. [Actionable topic creation] 3. [Actionable measurement setup] ``` --- #### Reference: references/research-documentation/SKILL.md # Research Documentation Architecture Audit existing documentation or plan a new suite using the Unified Frameworks for Technical Information Architecture. ## Core Rules - You are an architect, not a writer. Map structure and gaps; do not draft content. ## Procedure 1. Define the scope: identify the primary audience (novice vs. expert) and state the single-sentence "Core Assertion" (the value proposition). If existing docs have conflicting hooks, pick the most impactful or propose a synthesis. 2. Analyze existing content (if any): for each file determine its Diátaxis quadrant, EPPO status (standalone utility), and cognitive load. Use `references/checklist.md` for the completeness and accessibility items to check against. 3. Map the Snowflake outline: Core Assertion, Macro-Expansion, Component List, Topic Matrix by quadrant. 4. Identify gaps and friction: quadrant imbalance, structural plot-holes, and AI-readiness gaps. Use `references/llm-readiness.md` to assess `llms.txt`, MCP, RAG chunking, and dual-audience design. Use `references/metrics.md` to recommend measurement signals (TTFS, search analytics, coverage, freshness). 5. Produce the final research report using `references/report-template.md`. ## Rules - Categorize every document into exactly one Diátaxis quadrant. - Flag "Frankenbooks" (documents with mixed intent/quadrants). - Verify EPPO compliance: does each page establish its own context? - Do not start writing content; focus on architecture and gaps. - Do not suggest stylistic changes; focus on structural integrity. - The canonical theory lives in `content/research-documentation-frameworks.md`; the references here are operational excerpts that link back to it. ## Related Skills - `implement-documentation` — write topics from this audit. - `review-documentation` — review what you write. --- #### Reference: references/review-documentation/references/ai-readiness-criteria.md # AI-Readiness Criteria (Pass 5) Deep checks for Pass 5. The basic pass (TL;DR present, headers unique, Answer First) catches surface issues; these checks catch whether the page is actually consumable by an AI agent. The canonical theory is `content/research-documentation-frameworks.md` (section "Machine Readability"). ## LLM-friendly structure - Is there a concise TL;DR (1-2 sentences) at the top suitable for context-window injection? - Is the page free of navigation chrome when exported (menus, footers, ads) so the body text is clean? - Is prose minimalist and high-signal? Verbose docs cost more and retrieve worse. ## RAG-compatible chunking - Does the page cover one well-defined topic so it chunks cleanly for retrieval? - Are section headings stable and unique so a chunk can be addressed precisely? - Is there redundant cross-page duplication that would pollute retrieval results? ## Semantic headers - Are headers descriptive of content, not generic ("Overview", "Details")? - Are headers unique across the site so a model can disambiguate? - Is front matter present (title, description, version, category) for indexing? ## Dual-audience precision - Is language precise enough for a machine? Natural-language ambiguity a human resolves from context is opaque to an agent. - Are error conditions and their meanings explicit? - Are capability boundaries stated (what the tool/API can and cannot do)? ## Schema and spec sync (reference pages) - For API reference: is it generated from or synchronized with a machine-readable spec (OpenAPI, AsyncAPI, JSDoc/TypeDoc, Sphinx autodoc)? - For tool/agent docs: are MCP manifests and agent cards present with precise descriptions and JSON schemas for inputs/outputs? - Are code examples complete and runnable? Agents execute what they read; partial snippets mislead. ## Site-level (flag only if the page is the canonical entry) - Is a `llms.txt` present at the documentation root and does it reference this page where authoritative? - Are canonical URLs set so a model retrieves the current stable version? --- #### Reference: references/review-documentation/SKILL.md # Review Documentation Quality Perform a Rule of 5 review of the documentation using the Unified Frameworks for Technical Information Architecture. ## Core Rules - You are a reviewer, not a writer. Flag issues with locations; do not rewrite content. ## Procedure Perform 5 iterative passes. Check for convergence after each pass starting with Pass 2: report new CRITICAL issues, total new issues, the change vs. the previous pass, and status (CONVERGED or CONTINUE). Converge when no new CRITICAL issues are found and the new-issue rate drops below 10% versus the previous pass. Stop early if converged. ### Pass 1: Diátaxis & Intent Goal: does this topic have a single, clear intent? Checks: is it a Tutorial, How-to, Reference, or Explanation? Are there leaked intents (e.g., too much theory in a Tutorial)? Issue prefix: [INTENT-001]. ### Pass 2: EPPO & Standalone Utility Goal: can a foraging reader land here and succeed? Checks: are context and prerequisites established in the first two sentences? Does it rely on "previous chapter" knowledge without links? Issue prefix: [EPPO-001]. ### Pass 3: Cognitive Scannability (Info Mapping) Goal: can the reader scan the page in under 10 seconds and find the key answer? Checks: are descriptive labels used for every 2-3 paragraphs? Are paragraphs chunked into small units? Are tables and lists used for complex data? Issue prefix: [SCAN-001]. ### Pass 4: Accuracy, "Whole Game" & Fail-States Goal: is the content technically sound and resilient? Checks: are code snippets verified? Does it show the complete result? Are common errors documented? In tutorials, is the Martini Glass pattern followed (guided context then open exploration)? Issue prefix: [ACC-001]. ### Pass 5: Excellence & AI-Readiness Goal: is it production-ready and optimized for AI agents? Checks: is there a TL;DR for LLMs? Are headers semantically unique for RAG? Is the Answer First (Pyramid Principle) in the TL;DR and first paragraph? Use `references/ai-readiness-criteria.md` for the deep AI-readiness checks (`llms.txt`, RAG chunking, dual-audience, schema sync). Issue prefix: [EXCL-001]. ## Final Report - Total Issues by Severity (Critical, High, Medium, Low). - Top 3 Findings. - Verdict: Ready, Needs Revision, or Needs Rework. - Rationale. ## Rules - Reference exact locations (file, section, paragraph). - Validate issues exist; do not flag "potential" issues without evidence. - The canonical theory lives in `content/research-documentation-frameworks.md`; `references/ai-readiness-criteria.md` is an operational excerpt that links back to it. ## Related Skills - `research-documentation` — architecture-level gaps. - `implement-documentation` — fixing what the review finds.