# research-documentation (Unified Skill)

## Core Instructions (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: 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: 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: 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: 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]
```

---