Instructions
When bootstrapping documentation from a repository, follow the Documentation Planning Pyramid approach used by documentation experts:
┌─────────────────────────────────────────────────────────────────────┐
│ DOCUMENTATION PLANNING PYRAMID │
├─────────────────────────────────────────────────────────────────────┤
│ ┌─────────────┐ │
│ │ STRATEGY │ ← WHY (Step 1-2) │
│ │ Overview & │ │
│ │ Audience │ │
│ └──────┬──────┘ │
│ │ │
│ ┌───────────┴───────────┐ │
│ │ INFORMATION │ ← WHAT (Step 3-4) │
│ │ ARCHITECTURE │ │
│ └───────────┬───────────┘ │
│ │ │
│ ┌────────┴────────┐ │
│ │ APPROVAL │ ← CONFIRM (Step 5) │
│ │ User confirms │ │
│ │ IA structure │ │
│ └────────┬────────┘ │
│ │ │
│ ┌──────────────────┴──────────────────┐ │
│ │ CONTENT │ ← HOW (Step 6-8) │
│ │ Pages using Diátaxis Types │ │
│ └─────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
Phase 1: Strategy (WHY)
Step 1: Project Overview (Quick Scan)
Get a quick understanding of the project using git:
bash
# List all tracked files
git ls-files
# Get folder structure (top-level)
git ls-files | cut -d'/' -f1 | sort -u
# Check for key files
git ls-files | grep -E "(README|package\.json|openapi|swagger|schema\.graphql)"
Generate a brief project summary (<100 words):
📁 PROJECT OVERVIEW
Name: [from package.json or README]
Type: [API/Library/CLI/Web App]
Language: [TypeScript/Python/Go/etc.]
Framework: [Next.js/Express/FastAPI/etc.]
Structure:
├── src/ → Source code
├── lib/ → Library code
├── api/ → API routes
├── docs/ → Documentation (if exists)
└── tests/ → Test files
Key Files:
• README.md → Project description
• package.json → Dependencies
• openapi.json → API spec (if exists)
Summary: [One sentence describing what this project does]
If NO codebase found:
- Tell user: "No codebase detected. Creating docs-only project."
- Skip to Step 2
If `.devdoc/context.json` exists: Read and use existing preferences.
Step 2: Define Documentation Goals & Audience
Ask the user strategic questions before any scanning:
Question 1: Documentation Purpose (WHY)
What is the primary goal of this documentation?
1. **Enable team productivity** - Help internal developers work faster
2. **Onboard new developers** - Get new team members up to speed
3. **Support API consumers** - Help external devs integrate your API
4. **Guide product users** - Help end users accomplish tasks
5. **Inform stakeholders** - Communicate architecture and decisions
Question 2: Audiences & Roles (WHO)
Who are your documentation audiences?
═══════════════════════════════════════════════════════════
SINGLE vs MULTI-ROLE PRODUCTS
═══════════════════════════════════════════════════════════
Does your product have multiple user roles with different permissions?
A) **Single audience** - All users have same access
→ Example: Open-source library, public API
B) **Multiple roles** - Different users see different features
→ Example: SaaS with Admin/User roles, Enterprise with permissions
If Single Audience (A), choose one:
1. **Internal Developer** - Engineers on your team
→ Needs: Code flow, architecture, debugging, contribution guides
2. **External Developer** - API consumers, SDK users
→ Needs: Quick start, authentication, code examples, reference
3. **Product User** - End users of your product
→ Needs: Tutorials, feature guides, troubleshooting
4. **Content Author** - Technical writers, doc contributors
→ Needs: MDX syntax, structure guidelines, publishing workflow
5. **Product Manager/Stakeholder** - Non-technical team members
→ Needs: Feature overview, roadmap, IA map
If Multiple Roles (B), define your role matrix:
═══════════════════════════════════════════════════════════
ROLE MATRIX DEFINITION
═══════════════════════════════════════════════════════════
List your user roles and their permissions:
Example for a SaaS product:
┌─────────────────┬────────────────────────────────────────┐
│ Role │ Permissions / Features │
├─────────────────┼────────────────────────────────────────┤
│ Admin │ All features, user management, billing │
│ Editor │ Create/edit content, limited settings │
│ Viewer │ Read-only access │
│ API Developer │ API access, webhooks, integrations │
└─────────────────┴────────────────────────────────────────┘
Your roles:
1. Role name: _______
- Permissions: _______
- Key features: _______
2. Role name: _______
- Permissions: _______
- Key features: _______
(Add more as needed)
For Multi-Role Products, also ask:
How should role-specific content be organized?
1. **Separate sections** - Each role gets its own section/tab
docs/
├── admin/ # Admin-only guides
├── users/ # Regular user guides
└── developers/ # API/developer guides
2. **Inline badges** - Mixed content with role indicators
<RoleBadge roles={["admin", "editor"]}>
This feature is only available to Admins and Editors.
</RoleBadge>
3. **Permission gates** - Content varies by logged-in user
(Requires auth integration)
4. **Hybrid** - Combination of above
Question 3: Documentation Domain
What type of documentation are you creating?
1. **API Docs** - REST/GraphQL API reference for developers
→ Voice: Professional, code-focused
2. **Product Docs** - Feature guides and tutorials for end users
→ Voice: Friendly, approachable
3. **Internal Docs** - Team setup, architecture, contribution guides
→ Voice: Technical, direct
Question 4: API Type (if API Docs selected)
What type of API do you have?
1. **OpenAPI/REST** - I have an OpenAPI/Swagger spec
2. **GraphQL** - I have a GraphQL schema
3. **Both** - REST and GraphQL APIs
4. **Manual** - I'll document the API manually (no spec file)
Question 5: Code Examples Language
What language should code examples use?
(e.g., TypeScript, Python, curl, Go)
Phase 2: Information Architecture (WHAT)
Step 3: Locate & Import API Specs (if applicable)
Only if user selected OpenAPI or GraphQL:
For OpenAPI:
Do you have an OpenAPI spec file? Please provide the path, or I can search for:
- openapi.json / openapi.yaml
- swagger.json / swagger.yaml
For GraphQL:
Do you have a GraphQL schema? Please provide the path, or I can search for:
- schema.graphql / schema.gql
After locating spec:
- Copy to
api-reference/ folder - Validate the spec
- Extract metadata (endpoints, types, auth)
Step 4: Plan Content Using Diátaxis Framework
Classify each planned page by content type:
| Type | Purpose | When to Use | Example Pages | |
|---|
| Tutorial | Learning-oriented | First-time experience, guided learning | "Build Your First..." | |
| How-To Guide | Task-oriented | Accomplish specific goals | "Add Custom Domain", "Configure Theme" | |
| Reference | Information-oriented | Look up facts, specifications | Component props, CLI flags, Config schema | |
| Explanation | Understanding-oriented | Deeper comprehension | "How MDX Processing Works", Architecture | |
Map documentation structure based on domain:
For API Docs:
docs/
├── index.mdx # [Explanation] Overview, value prop
├── quickstart.mdx # [Tutorial] 5-min getting started
├── authentication.mdx # [How-To] Auth setup
├── guides/
│ ├── overview.mdx # [Explanation] Core concepts
│ └── {use-cases}.mdx # [How-To] Common use cases
├── api-reference/
│ ├── openapi.json # Imported spec
│ ├── introduction.mdx # [Explanation] API overview
│ └── errors.mdx # [Reference] Error codes
└── sdks/ # [Reference] SDK docs
For Product Docs:
docs/
├── index.mdx # [Explanation] Product overview
├── getting-started/
│ ├── quickstart.mdx # [Tutorial] First experience
│ └── key-concepts.mdx # [Explanation] Core concepts
├── features/
│ └── {feature}.mdx # [How-To] Feature guides
├── tutorials/
│ └── {tutorial}.mdx # [Tutorial] Step-by-step learning
└── troubleshooting/ # [How-To] Problem solving
For Multi-Role Products (with separate sections):
docs/
├── index.mdx # [Explanation] Product overview (all roles)
├── getting-started/
│ ├── quickstart.mdx # [Tutorial] First experience (all roles)
│ └── key-concepts.mdx # [Explanation] Core concepts (all roles)
│
├── admin/ # 🔒 ADMIN-ONLY SECTION
│ ├── overview.mdx # [Explanation] Admin dashboard overview
│ ├── user-management.mdx # [How-To] Manage users & permissions
│ ├── billing.mdx # [How-To] Billing & subscriptions
│ ├── settings.mdx # [Reference] Admin settings
│ └── audit-logs.mdx # [Reference] Audit & compliance
│
├── users/ # 👤 REGULAR USER SECTION
│ ├── overview.mdx # [Explanation] User dashboard
│ ├── features/ # [How-To] Feature guides
│ └── account.mdx # [How-To] Account settings
│
├── developers/ # 💻 DEVELOPER SECTION
│ ├── overview.mdx # [Explanation] API overview
│ ├── authentication.mdx # [How-To] API auth
│ ├── webhooks.mdx # [How-To] Webhook setup
│ └── api-reference/ # [Reference] API docs
│
└── troubleshooting/ # [How-To] Problem solving (all roles)
For Multi-Role Products (with inline badges):
When using inline role badges, add to each page's frontmatter:
---
title: User Management
description: Add and manage users in your organization
roles: ["admin", "owner"] # Roles that can access this feature
---
<RoleBadge roles={["admin", "owner"]}>
This feature requires Admin or Owner permissions.
</RoleBadge>
## Overview
User management allows you to...
Role-Specific Content Patterns:
Pattern 1: Conditional sections within a page
mdx
## Basic Settings
All users can configure these settings...
<RoleSection roles={["admin"]}>
## Advanced Settings (Admin Only)
Administrators can additionally configure...
</RoleSection>
Pattern 2: Feature availability matrix
mdx
## Feature Availability
| Feature | Viewer | Editor | Admin |
|---------|--------|--------|-------|
| View dashboards | ✅ | ✅ | ✅ |
| Edit content | ❌ | ✅ | ✅ |
| Manage users | ❌ | ❌ | ✅ |
| Billing access | ❌ | ❌ | ✅ |