---
name: bootstrap-docs
description: Expert-level documentation bootstrap using Diátaxis framework and audience-driven planning.
---

## 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: Primary Audience (WHO)
```
Who is your PRIMARY audience? (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
```

#### 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:**
1. Copy to `api-reference/` folder
2. Validate the spec
3. 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 Internal Docs:
```
docs/
├── index.mdx              # [Explanation] Project overview
├── getting-started/
│   ├── setup.mdx          # [How-To] Environment setup
│   └── prerequisites.mdx  # [Reference] Requirements
├── architecture/
│   ├── overview.mdx       # [Explanation] System design
│   ├── data-flow.mdx      # [Explanation] How data flows
│   └── decisions/         # [Explanation] ADRs
├── development/
│   ├── workflow.mdx       # [How-To] Dev workflow
│   └── debugging.mdx      # [How-To] Debugging guide
└── contributing.mdx       # [How-To] Contribution guide
```

### Step 5: Present IA for Approval (REQUIRED)

**IMPORTANT: Always get user approval before generating documentation.**

Present the **complete Information Architecture** to the user, covering:
1. **Navigation Structure** - Tabs, groups, and page ordering (what users see in sidebar)
2. **File Structure** - Actual files to be created
3. **Content Summary** - Diátaxis content type breakdown

```
📋 PROPOSED DOCUMENTATION ARCHITECTURE

Based on your preferences:
  - Goal: [selected goal]
  - Audience: [primary audience]  
  - Domain: [api/product/internal]

═══════════════════════════════════════════════════════════════
                      NAVIGATION STRUCTURE
           (How documentation appears in the sidebar)
═══════════════════════════════════════════════════════════════

📑 TAB: Guides
├── 📁 Getting Started
│   ├── Introduction                    # index.mdx [explanation]
│   ├── Quickstart                      # quickstart.mdx [tutorial]
│   └── Authentication                  # authentication.mdx [how-to]
│
├── 📁 Core Concepts
│   ├── Overview                        # guides/overview.mdx [explanation]
│   ├── Working with Resources          # guides/resources.mdx [how-to]
│   └── Error Handling                  # guides/errors.mdx [how-to]
│
└── 📁 SDKs
    └── TypeScript SDK                  # sdks/typescript.mdx [reference]

📑 TAB: API Reference (OpenAPI)
└── [Auto-generated from openapi.json]
    ├── Introduction                    # api-reference/introduction.mdx [explanation]
    ├── Authentication                  # (from spec)
    ├── Endpoints                       # (from spec)
    └── Error Codes                     # api-reference/errors.mdx [reference]

═══════════════════════════════════════════════════════════════
                        FILE STRUCTURE
              (Actual files to be created in docs/)
═══════════════════════════════════════════════════════════════

docs/
├── index.mdx                 # Introduction
├── quickstart.mdx            # Quickstart guide
├── authentication.mdx        # Auth setup
├── guides/
│   ├── overview.mdx          # Core concepts
│   ├── resources.mdx         # Working with resources
│   └── errors.mdx            # Error handling
├── api-reference/
│   ├── openapi.json          # Imported spec
│   ├── introduction.mdx      # API overview
│   └── errors.mdx            # Error codes reference
└── sdks/
    └── typescript.mdx        # TypeScript SDK

═══════════════════════════════════════════════════════════════
                       CONTENT SUMMARY
═══════════════════════════════════════════════════════════════

By Diátaxis Content Type:
  📚 Tutorials: 1 page
     └── quickstart.mdx
  
  📝 How-To Guides: 4 pages
     ├── authentication.mdx
     ├── guides/resources.mdx
     └── guides/errors.mdx
  
  📖 Reference: 2 pages
     ├── api-reference/errors.mdx
     └── sdks/typescript.mdx
  
  💡 Explanations: 3 pages
     ├── index.mdx (overview)
     ├── guides/overview.mdx
     └── api-reference/introduction.mdx

Total: 10 pages to generate

═══════════════════════════════════════════════════════════════
                         GAPS ANALYSIS
═══════════════════════════════════════════════════════════════

Potential missing documentation:
  ⚠️  No troubleshooting guide
  ⚠️  No changelog/release notes
  ⚠️  No migration guide

───────────────────────────────────────────────────────────────

Does this architecture look complete?

1. ✅ **Approve** - Generate documentation with this structure
2. ✏️  **Modify** - I want to add/remove/change pages or navigation
3. ➕ **Add suggested** - Add the suggested missing docs
4. ❌ **Restart** - Let's reconsider the goals and audience
```

**If user chooses "Modify":**
- Ask what they want to change:
  - Add/remove pages?
  - Change navigation grouping?
  - Rename tabs or groups?
  - Reorder pages?
- Update the proposed structure
- Present again for approval

**If user chooses "Add suggested":**
- Add the suggested missing documentation to the plan
- Present updated structure for final approval

**If user chooses "Restart":**
- Go back to Step 2 (Define Documentation Goals & Audience)

**If user chooses "Approve":**
- Proceed to Step 6 (Create Context File)

**What the IA approval covers:**

| Aspect | What's Shown |
|--------|--------------|
| **Navigation** | Tabs, groups, page ordering (sidebar view) |
| **Files** | Actual file paths and folder structure |
| **Content Types** | Diátaxis classification per page |
| **Gaps** | Suggested missing documentation |
| **Scope** | Total page count and effort estimate |

**Why this step matters:**
- Clarifies exactly what will be created
- Shows how users will navigate the docs
- Identifies missing documentation before writing
- Allows user to adjust navigation structure
- Prevents wasted effort on unwanted content
- Ensures alignment on scope and priorities

### Step 6: Create Context File (After Approval)

Save to `.devdoc/context.json`:
```json
{
  "$schema": "https://devdoc.sh/schemas/context.json",
  "version": "1.0",
  "lastUpdated": "2026-01-25T10:00:00Z",
  
  "strategy": {
    "goal": "Support API consumers",
    "audience": {
      "primary": "External Developer",
      "needs": ["Quick start", "Authentication", "Code examples", "Reference"]
    }
  },
  
  "preferences": {
    "docType": "api",
    "apiType": "openapi",
    "codeLanguage": "TypeScript"
  },
  
  "product": {
    "name": "Product Name",
    "description": "From README",
    "type": "api"
  },
  
  "api": {
    "style": "REST",
    "specPath": "api-reference/openapi.json",
    "baseUrl": "https://api.example.com"
  },
  
  "documentation": {
    "voice": "professional",
    "codeExamples": {
      "primaryLanguage": "TypeScript"
    }
  },
  
  "contentPlan": {
    "approved": true,
    "approvedAt": "2026-01-25T10:00:00Z",
    "pages": [
      { "path": "index.mdx", "type": "explanation", "priority": "high", "status": "planned" },
      { "path": "quickstart.mdx", "type": "tutorial", "priority": "high", "status": "planned" },
      { "path": "authentication.mdx", "type": "how-to", "priority": "high", "status": "planned" },
      { "path": "guides/overview.mdx", "type": "explanation", "priority": "medium", "status": "planned" },
      { "path": "api-reference/errors.mdx", "type": "reference", "priority": "medium", "status": "planned" }
    ]
  }
}
```

### Step 7: Generate Documentation

**Only proceed after user has approved the IA structure in Step 5.**

**Use project overview and Diátaxis principles:**

#### Writing Guidelines (Expert Standards)

1. **Use Second Person** - "You can configure..." not "Users can configure..."
2. **Active Voice** - "Run the command" not "The command should be run"
3. **Task-Oriented Headings** - "How to add a custom domain" not "Custom domains"
4. **Include Examples** - Every concept needs a code example
5. **Progressive Disclosure** - Basic → Advanced ordering

#### Page Structure by Content Type

**Tutorial Template:**
```mdx
---
title: Build [Something] with [Technology]
description: A complete tutorial to [achieve outcome] from scratch
contentType: tutorial
---

## What You'll Build

[End result description + estimated time]

## Prerequisites

<Note>Before you begin, ensure you have: [requirements]</Note>

## Steps

<Steps>
  <Step title="Step 1">Content</Step>
  <Step title="Step 2">Content</Step>
</Steps>

## Next Steps

[Links to related content]
```

**How-To Guide Template:**
```mdx
---
title: How to [Achieve Specific Goal]
description: Learn how to [specific outcome]
contentType: how-to
---

## Overview

[2-3 sentences: What, Who, Why]

## Prerequisites (if applicable)

## Steps

<Steps>
  <Step title="[Action verb] [object]">Content</Step>
</Steps>

## Example

[Complete working example]

## Next Steps
```

**Reference Template:**
```mdx
---
title: [Component/API/Config] Reference
description: Complete reference for [topic]
contentType: reference
---

## Overview

[Brief description]

## Properties/Parameters

| Property | Type | Description | Default |
|----------|------|-------------|---------|
| ... | ... | ... | ... |

## Examples

## Related

[Links to related references]
```

**Explanation Template:**
```mdx
---
title: Understanding [Concept]
description: Deep dive into [topic] and how it works
contentType: explanation
---

## Overview

[Why this matters]

## How It Works

[Conceptual explanation with diagrams]

## Key Concepts

## When to Use

## Related

[Links to tutorials and how-tos that apply this concept]
```

### Step 8: Update docs.json

Configure navigation based on doc type:

**API Docs with OpenAPI:**
```json
{
  "name": "Product Name",
  "docType": "api",
  "navigation": {
    "tabs": [
      {
        "tab": "Guides",
        "groups": [
          {
            "group": "Getting Started",
            "icon": "rocket-launch",
            "pages": ["index", "quickstart", "authentication"]
          },
          {
            "group": "Guides",
            "icon": "book-open",
            "pages": ["guides/overview"]
          }
        ]
      },
      {
        "tab": "API Reference",
        "type": "openapi",
        "spec": "api-reference/openapi.json"
      }
    ]
  }
}
```

### Step 9: Summary

```
✅ Documentation Generated!

Strategy:
  - Goal: [selected goal]
  - Audience: [primary audience]
  - Domain: [api/product/internal]

Content Plan (Diátaxis):
  - Tutorials: X pages
  - How-To Guides: X pages
  - Reference: X pages
  - Explanations: X pages

Files created:
  - docs.json (navigation)
  - .devdoc/context.json (strategy & preferences)
  - [list of mdx files with content types]

Next steps:
  1. Run `devdoc dev` to preview
  2. Review TODO markers in generated docs
  3. Run `/whisk-theme` to match your branding
```

---

## Key Principles

| Principle | Description |
|-----------|-------------|
| **Project overview first** | Quick scan using git to understand structure |
| **Strategy first** | Define goals and audience before structure |
| **Audience-driven** | Match content to user needs |
| **Diátaxis types** | Classify every page by content type |
| **IA approval required** | Always get user approval before generating content |
| **Expert writing** | Second person, active voice, task-oriented |
| **Mark unknowns** | Add TODO for sections needing review |

## Quality Checklist

Before completing, verify:

- [ ] Title is clear and specific
- [ ] Introduction explains the "why"
- [ ] Content type matches page purpose
- [ ] Code examples are complete and tested
- [ ] Links to related docs included
- [ ] Follows writing guidelines (2nd person, active voice)
- [ ] Progressive disclosure (basic → advanced)
