Instrucciones de origen · Vista previa de solo lectura
name
doc-site-builder
description
Documentation site architecture: information hierarchy, nav structure, content templates, search strategy
Doc Site Builder Skill
When to activate
Starting a new documentation site from scratch and need an information architecture
Migrating docs from a wiki (Notion, Confluence) or README files to a dedicated docs site
An existing docs site has outgrown its structure and needs a IA redesign
You need to define content templates so multiple contributors produce consistent pages
Planning a docs-as-code workflow where engineers and writers collaborate in the same repo
When NOT to use
You need to write individual docs pages — use /api-doc-writer or /readme-generator for specific content
You're choosing a docs platform (Docusaurus vs MkDocs vs Mintlify vs GitBook) — this skill covers architecture, not platform selection; make that decision first
You want to audit existing docs quality — this is a structural and architecture skill, not an audit tool
You need to set up the technical build pipeline — this skill produces the architecture; implementation is an engineering task
Instructions
Full docs site architecture
Design the information architecture for a documentation site.
## Context
Product: [name and 1-sentence description]
Audience: [who reads these docs — end users / developers / admins / all three]
Doc types needed: [getting started / API reference / how-to guides / conceptual guides / release notes / troubleshooting / all]
Current state: [new from scratch / migrating from [source] / restructuring existing site]
Content volume: [approximate number of pages — rough estimate is fine]
Team: [who writes: [N] technical writers / engineers write their own / mixed]
Platform chosen: [Docusaurus / MkDocs / Mintlify / GitBook / Notion / custom / not yet chosen]
## Produce:
### 1. Information architecture overview
Top-level navigation structure with rationale for each section:
For each top-level section: explain the user intent it serves and the content it contains.
### 2. Content taxonomy
Define the four Diátaxis content types for this product:
**Tutorials** (learning-oriented, guided experience):
- When to write a tutorial vs a how-to guide
- Template for tutorials in this product context
- Example tutorial titles for this product
**How-to Guides** (task-oriented, problem-solving):
- When to write a how-to vs a tutorial
- Template for how-to guides
- Example how-to titles for this product
**Reference** (information-oriented, look-up):
- What belongs in reference (API endpoints, config keys, CLI flags, data models)
- Template for reference pages
- How reference is auto-generated vs hand-written for this product
**Explanation / Conceptual** (understanding-oriented):
- What concepts need explanation docs for this product
- Template for concept pages
- Example concept topics for this product
### 3. Page templates
Provide fill-in-the-blank templates for:
**Getting Started / Quick Start template:**
```markdown
# Getting Started with [Product]
## What you'll build
[1-2 sentences — the outcome the reader achieves]
## Prerequisites
- [requirement 1]
- [requirement 2]
## Step 1: [First action]
[instruction]
```[language]
[code example]
Expected output:
[what they see when it works]
Step 2: [Next action]
[instruction]
What just happened
[Brief explanation of what the quick start code does — builds mental model]
Next steps
[Link to next tutorial]
[Link to relevant how-to]
[Link to reference]
**How-to Guide template:**
```markdown
# How to [accomplish specific task]
[One sentence: who this is for and what it achieves]
## Prerequisites
- [What they need before starting]
## Steps
### 1. [First step]
[instruction — imperative voice, second person]
```[language]
[code]
2. [Second step]
[instruction]
Troubleshooting
[Common problem]: [Solution]
[Common error message]: [What it means and how to fix it]
Related
[How-to guide that often pairs with this one]
[Reference page for the main config/API used here]
**Reference page template:**
```markdown
# [Configuration key / API endpoint / CLI command name]
[One sentence describing what this does]
## Syntax / Signature
[exact syntax]
## Parameters / Options
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `name` | string | Yes | — | [what it does] |
| `timeout` | number | No | 30 | [what it does] |
## Example
```[language]
[minimal working example]
Notes
[Edge cases, gotchas, version constraints]
See also
[Related reference items]
### 4. Navigation design rules
Principles for this docs site's navigation:
- Maximum depth: [2 / 3 levels — pick one; deeper is almost always worse]
- Sidebar: [always visible / collapsed on mobile / section-scoped]
- Breadcrumbs: [yes / no — yes for deep hierarchies]
- Page length: [max recommended length and when to split into sub-pages]
- Versioning: [does the site need to version docs? Strategy for how]
### 5. Search strategy
- Search tool: [Algolia DocSearch / built-in full-text / pagefind / none]
- Search optimisation: what metadata to add to every page (title, description, tags)
- Faceting / filtering: does the audience need to filter by role, product tier, or version?
### 6. Contributor workflow
How engineers and writers collaborate:
- File naming convention: [kebab-case.md / topic/subtopic.md]
- PR review process: [writer reviews all PRs touching docs / engineer self-merges with review from writer]
- Freshness signal: last_updated frontmatter on every page
- Broken link checking: [CI step — use which tool]
- Style guide location: [link or embed]
### 7. Launch readiness checklist
- [ ] Home page has clear paths to the 3 most common user intents
- [ ] Every page has a title, description, and last_updated
- [ ] All code examples are tested and runnable
- [ ] Search is configured and indexed
- [ ] 404 page has useful navigation back to content
- [ ] Analytics configured (pageviews, search queries, 404s)
- [ ] Feedback widget on each page ("Was this helpful?")
- [ ] Broken link check passes in CI
Diátaxis content classification
Classify this content by Diátaxis type and tell me what's missing.
I have the following docs pages (list titles and 1-line description):
[list your existing pages]
For each page:
1. Classify as: Tutorial / How-to / Reference / Explanation / Unclear / Mixed (flag mixed as a problem)
2. Flag pages that are "mixed" type — they need to be split
3. Identify which Diátaxis quadrants have content gaps for this product
Gap analysis output:
| Diátaxis type | Coverage | Missing topics |
|---|---|---|
| Tutorial | Good / Thin / None | [what's missing] |
| How-to | Good / Thin / None | [what's missing] |
| Reference | Good / Thin / None | [what's missing] |
| Explanation | Good / Thin / None | [what's missing] |
Recommended priority: [which type to write more of first, and why]
Docs site analytics interpretation
Interpret docs site analytics and surface content problems.
Analytics source: [Google Analytics / Plausible / Posthog / custom]
Data available:
- Top 10 pages by pageviews: [paste]
- Top 10 search queries: [paste]
- Pages with highest exit rate: [paste]
- 404 errors (top broken paths): [paste]
Analyse:
1. SEARCH QUERIES THAT FIND NOTHING: queries in the search log with 0 results = content gap. List them.
2. HIGH-EXIT PAGES: pages with very high exit rate may be failing to answer the user's question. Diagnose the top 3.
3. MISSING PAGES (404s): list broken paths — which of these represent real content that should exist?
4. UNDERPERFORMING PAGES: pages that should be high-traffic but aren't. What might explain the gap?
Output: prioritised content backlog based on analytics evidence.
Example
User: I'm building docs for a developer-facing webhook integration library. Users are engineers integrating our API. I need to go from 3 README files to a proper docs site on Docusaurus. Expected: ~40 pages total.
Output (excerpt):
## Information Architecture: Webhook Library Docs### Top-level navigation
### Content gap analysis
Your 3 README files likely cover: installation, basic usage, and some API reference.
Missing (high priority):
- Tutorial: "Receive your first webhook in 5 minutes" — this is the entry point for all new users
- How-to: "Test webhooks locally with ngrok or Cloudflare Tunnel" — most common friction point for developers
- Concept: "Retry and ordering guarantees" — engineers will need this before using in production
- Reference: Event types catalogue — should be auto-generated from your schema, not hand-written
