dojo.md 0.2.1 → 0.2.3

package/courses/api-documentation-writing/scenarios/level-4/expert-documentation-shift.yaml

@@ -0,0 +1,45 @@
+meta:
+  id: expert-documentation-shift
+  level: 4
+  course: api-documentation-writing
+  type: output
+  description: "Combined expert shift — redesign an organization's entire API documentation program including governance, portal, testing, metrics, and team structure"
+  tags: [API, documentation, combined, shift-simulation, program, expert]
+
+state: {}
+
+trigger: |
+  You've been hired as Head of Developer Experience at a mid-size SaaS
+  company. The API documentation situation:
+
+  - 5 product teams, each maintaining docs differently
+  - 3 public APIs (payments, analytics, messaging) — 150 endpoints total
+  - Documentation in 3 places: Confluence wiki, README files, Swagger UI
+  - No style guide, no review process, no metrics
+  - Developer satisfaction survey: 3.2/10 for documentation
+  - Support ticket volume: 200/month, 60% are "how do I..." questions
+  - Competitor launched a developer portal — you're losing deals
+  - Budget: 2 technical writers, $200K for tooling
+
+  Your mandate: bring documentation satisfaction to 8/10 within 12 months
+  and reduce doc-related support tickets by 70%.
+
+  Task: Present your complete 12-month documentation transformation
+  plan. Include: current state assessment, target architecture,
+  tooling decisions, team structure, governance, metrics framework,
+  quarterly milestones, and the first 30-day quick wins. This is
+  your proposal to the VP of Engineering.
+
+assertions:
+  - type: llm_judge
+    criteria: "Assessment and target state are clear — current state audit: catalog all documentation across Confluence/README/Swagger, identify gaps (undocumented endpoints, outdated pages, broken examples), analyze support tickets for top documentation failures, benchmark against competitor portal. Target state: unified developer portal (single source of truth), docs-as-code workflow (Git-based), automated quality checks, self-service onboarding, measurable developer satisfaction. Gap analysis: what exists vs what's needed, effort estimate for each gap. Risk assessment: team capacity, migration complexity, organizational change resistance"
+    weight: 0.35
+    description: "Assessment"
+  - type: llm_judge
+    criteria: "12-month plan with quarterly milestones is realistic — Q1 (foundation): migrate to docs-as-code, set up portal skeleton, write style guide, implement top-5 support-ticket-reducing guides, quick win: consolidate all docs to one URL. Q2 (content): complete API reference for all 150 endpoints, add interactive explorer, write quickstart guides for all 3 APIs, launch sandbox documentation. Q3 (quality): implement automated testing (contract tests, link checks, example validation), set up documentation metrics dashboard, launch feedback mechanism on every page. Q4 (maturity): multi-language code examples, partner documentation, documentation governance enforced across all teams, advanced guides. 30-day quick wins that show immediate value to build organizational buy-in"
+    weight: 0.35
+    description: "Execution plan"
+  - type: llm_judge
+    criteria: "Team, tooling, and metrics are concrete — team structure: 2 technical writers (one for content creation, one for developer experience/tooling), part-time contributions from each product team (documentation champion per team). Tooling budget: portal framework ($0 open-source — Docusaurus/Nextra), hosting (Vercel/Netlify, $200/month), search (Algolia DocSearch, free for open docs), analytics (Plausible, $100/month), testing (custom CI, minimal cost) — well under $200K. Remaining budget for: translation, design, external contractors for migration. Metrics: TTFC target <15 minutes, support ticket reduction tracked monthly, documentation satisfaction quarterly survey, documentation coverage (% endpoints with examples), automated health score. Success criteria clearly mapped to the 8/10 satisfaction and 70% ticket reduction targets"
+    weight: 0.30
+    description: "Team and metrics"

package/courses/api-documentation-writing/scenarios/level-4/multi-audience-docs.yaml

@@ -0,0 +1,46 @@
+meta:
+  id: multi-audience-docs
+  level: 4
+  course: api-documentation-writing
+  type: output
+  description: "Write for multiple audiences — create documentation that serves beginners, experienced developers, architects, and non-technical stakeholders from one source"
+  tags: [API, documentation, multi-audience, personas, content-strategy, expert]
+
+state: {}
+
+trigger: |
+  Your API documentation must serve radically different audiences:
+
+  1. Junior developers: need hand-holding, explanations of REST concepts,
+     step-by-step tutorials
+  2. Senior developers: want endpoint reference, skip to code examples,
+     hate reading obvious explanations
+  3. Architects: need security model, rate limits, SLA, data residency,
+     compliance certifications
+  4. Product managers: need capability overview, integration timeline
+     estimates, pricing implications
+  5. Partner integrators: need everything above plus contractual SLA,
+     sandbox access, certification program
+
+  Currently your docs serve none of them well — too advanced for
+  juniors, too basic for seniors, missing architect info, impenetrable
+  for PMs.
+
+  Task: Design a multi-audience documentation strategy. Show how to
+  serve all five audiences from a single documentation system without
+  maintaining five separate doc sets. Include: content layering, persona
+  routing, progressive disclosure, and conditional content techniques.
+
+assertions:
+  - type: llm_judge
+    criteria: "Content layering serves different expertise levels — progressive disclosure: start with simple explanation, expand for complexity. Pattern: summary (everyone reads) → quick start (beginners follow, seniors skip) → reference (seniors use) → deep dive (architects read). Implementation: collapsible sections ('Show advanced options'), tabbed content (beginner/advanced), difficulty indicators on pages. Landing page acts as router: 'I want to...' with persona-based paths. API reference: concise by default with expandable details (field descriptions, edge cases). Tutorial: clear 'Prerequisites' section so seniors skip what they know. Don't dumb down — layer up"
+    weight: 0.35
+    description: "Content layering"
+  - type: llm_judge
+    criteria: "Each audience gets what they need — junior developers: learning path (concepts → tutorials → reference), glossary of terms (what is idempotency?), copy-paste examples that work. Senior developers: search-first (find endpoint fast), curl examples, response schemas, skip to code. Architects: dedicated section — security whitepaper, compliance certifications (SOC2, HIPAA), architecture diagrams, SLA (99.9% uptime), data flow diagrams, disaster recovery, encryption at rest/in transit. Product managers: API capabilities overview (no code), integration effort estimates, use case galleries, pricing per API call. Partners: everything plus sandbox provisioning, certification program, co-branded documentation, dedicated support SLA"
+    weight: 0.35
+    description: "Audience-specific content"
+  - type: llm_judge
+    criteria: "Single-source strategy avoids content duplication — content reuse: write once, surface in multiple contexts (endpoint description appears in reference AND tutorial). Dynamic content: role-based content visibility (architect sees security section, developer sees code section) — implement with frontmatter tags and build-time filtering. Shared components: authentication section written once, embedded in every relevant guide. URL structure: /docs/reference/... (all audiences), /docs/guides/getting-started (beginners), /docs/architecture/security (architects), /docs/overview (PMs). Maintenance: single source in repo, build generates audience-specific views. Content model: each page has metadata (audience, difficulty, prerequisites) enabling smart navigation"
+    weight: 0.30
+    description: "Single-source strategy"

package/courses/api-documentation-writing/scenarios/level-5/ai-powered-documentation.yaml

@@ -0,0 +1,44 @@
+meta:
+  id: ai-powered-documentation
+  level: 5
+  course: api-documentation-writing
+  type: output
+  description: "Design AI-powered documentation — envision how AI transforms API documentation creation, maintenance, personalization, and developer interaction"
+  tags: [API, documentation, AI, LLM, automation, future, personalization, master]
+
+state: {}
+
+trigger: |
+  The CTO asks: "AI is changing everything. How will it change API
+  documentation? Should we invest in traditional docs or bet on AI?"
+
+  Current landscape:
+  - LLMs can generate documentation from code
+  - AI chatbots can answer developer questions from docs
+  - Code generation tools (Copilot) may reduce need for examples
+  - AI can translate docs to any language instantly
+  - But: AI hallucinations in technical docs are dangerous
+  - And: AI-generated docs often lack nuance and design decisions
+
+  Your company has 200 endpoints, 50K pages of documentation, and
+  5,000 active developers.
+
+  Task: Write a strategic assessment of AI's impact on API documentation.
+  Include: what AI can automate today, what it can't, how to use AI
+  to enhance (not replace) documentation, risks and mitigations, and
+  a 3-year technology roadmap for AI-powered developer documentation.
+  Be honest about limitations — the CTO will see through hype.
+
+assertions:
+  - type: llm_judge
+    criteria: "Assessment of AI capabilities is honest and specific — what AI can do today: (1) generate first-draft documentation from code and OpenAPI specs (70% quality, needs human review), (2) translate documentation across languages (good for technical content), (3) answer developer questions from existing docs (RAG-based chatbot), (4) detect documentation drift (compare docs to code), (5) generate code examples from endpoint descriptions. What AI cannot do well: (1) write design decision explanations (why, not what), (2) create meaningful tutorials (requires understanding developer journey), (3) maintain consistent voice and style across docs, (4) understand business context for error messages, (5) design information architecture. Honest assessment: AI is a force multiplier for writers, not a replacement. Removes 50% of toil, human focuses on remaining 50% of high-value content"
+    weight: 0.35
+    description: "Honest AI assessment"
+  - type: llm_judge
+    criteria: "AI enhancement strategy is practical — immediate wins: (1) AI documentation assistant chatbot — developer asks question, chatbot answers from docs with source citations, escalates to human when uncertain. (2) Automated drift detection — AI compares OpenAPI spec changes to documentation, flags outdated sections. (3) Code example generation — AI generates examples in multiple languages from curl templates. (4) Translation — AI translates docs to Japanese/Portuguese with human review for technical accuracy. Medium-term: (5) Personalized docs — AI adapts content to developer's skill level and language preference. (6) Smart search — semantic search that understands intent, not just keywords. (7) Automated API reference from code — generates and maintains reference docs with human oversight. Each initiative: implementation approach, expected impact, risk mitigation for hallucinations"
+    weight: 0.35
+    description: "Enhancement strategy"
+  - type: llm_judge
+    criteria: "Risks and 3-year roadmap are credible — risks: (1) hallucination — AI generates plausible but incorrect documentation (mitigation: always cite source, human review pipeline, automated testing against actual API). (2) Homogeneous voice — AI docs all sound the same (mitigation: style guide fine-tuning, human editors). (3) Over-reliance — team skills atrophy (mitigation: AI assists, doesn't replace). (4) Privacy — proprietary API designs exposed to AI providers (mitigation: self-hosted models, data boundaries). 3-year roadmap: Year 1 — chatbot + drift detection + translation (proven technologies, immediate value). Year 2 — personalized documentation + AI-generated examples + automated reference (emerging capabilities, measured rollout). Year 3 — intelligent documentation platform where docs learn from developer behavior and adapt (aspirational, depends on year 1-2 learnings). Budget: 20% of documentation budget allocated to AI tooling"
+    weight: 0.30
+    description: "Risks and roadmap"

package/courses/api-documentation-writing/scenarios/level-5/api-first-documentation.yaml

@@ -0,0 +1,45 @@
+meta:
+  id: api-first-documentation
+  level: 5
+  course: api-documentation-writing
+  type: output
+  description: "Document API-first strategy — write documentation that enables an API-first organizational transformation where APIs are products designed for external consumption"
+  tags: [API, documentation, api-first, design-first, organizational, transformation, master]
+
+state: {}
+
+trigger: |
+  Your company is transitioning to API-first: every capability must be
+  available as a well-documented API, not just internal microservices
+  with Swagger UI. This means:
+
+  - 40 internal APIs need to become "productized" (external-quality docs)
+  - API design happens before implementation (design-first)
+  - Documentation is part of the API definition, not an afterthought
+  - Every team must think about external developers as users
+
+  Resistance:
+  - "We don't have time to write docs for internal APIs"
+  - "Our APIs are too complex for external developers"
+  - "Documentation slows down development"
+  - "We'll document it when it's ready" (it's never ready)
+
+  Task: Write the API-first documentation playbook. Include: the
+  design-first documentation process, how to transform internal APIs
+  into externally documented products, team workflows that integrate
+  documentation into development, and organizational change management
+  for the "documentation is mandatory" mindset shift.
+
+assertions:
+  - type: llm_judge
+    criteria: "Design-first process integrates documentation into development — workflow: (1) write API description (OpenAPI spec) before writing code, (2) review spec with stakeholders (including documentation quality), (3) generate mock server from spec for early feedback, (4) implement against the spec, (5) automated tests verify implementation matches spec, (6) documentation auto-generated from spec, (7) tech writer enhances with guides and tutorials. Documentation is a first-class artifact: just like tests, code cannot ship without documentation meeting quality bar. Definition of Done includes: OpenAPI spec complete, at least one example per endpoint, error codes documented, changelog entry written. API design review checklist includes documentation quality criteria"
+    weight: 0.35
+    description: "Design-first process"
+  - type: llm_judge
+    criteria: "Internal-to-external transformation is practical — assessment: score each internal API on 'external readiness' (documentation quality, naming consistency, error handling, authentication, rate limiting). Transformation tiers: Tier 1 (quick wins, 2 weeks): add descriptions to OpenAPI spec, add examples, standardize error format. Tier 2 (moderate, 1-2 months): implement consistent authentication, add rate limiting, write getting started guide, set up sandbox. Tier 3 (significant, 3-6 months): redesign API surface for external usability, comprehensive documentation, SDK generation, interactive explorer. Prioritization: transform APIs by business value (revenue potential × developer demand). Templates and checklists for each tier. Budget estimation framework: effort per API based on current state"
+    weight: 0.35
+    description: "Transformation playbook"
+  - type: llm_judge
+    criteria: "Change management addresses organizational resistance — address each objection: 'No time for docs' → documentation templates reduce effort to 30 minutes per endpoint, automated generation handles 60% of content. 'Too complex' → if developers can't understand it, the API design needs improvement (docs expose design problems). 'Slows development' → design-first actually speeds development (catch issues earlier, fewer integration bugs). 'We'll do it later' → documentation debt compounds like technical debt (quantify the cost). Incentive alignment: documentation quality in team performance metrics, API maturity scorecard visible to leadership, celebrate teams that achieve documentation excellence. Training program: documentation writing workshops, OpenAPI authoring training, peer mentorship (pair high-quality team with struggling team). Executive sponsorship: VP-level champion who holds teams accountable"
+    weight: 0.30
+    description: "Change management"

package/courses/api-documentation-writing/scenarios/level-5/api-marketplace-docs.yaml

@@ -0,0 +1,42 @@
+meta:
+  id: api-marketplace-docs
+  level: 5
+  course: api-documentation-writing
+  type: output
+  description: "Document API marketplace — create documentation standards and templates for an API marketplace where multiple providers list their APIs for discovery and integration"
+  tags: [API, documentation, marketplace, platform, multi-provider, standards, master]
+
+state: {}
+
+trigger: |
+  Your company is launching an API marketplace — a platform where
+  third-party providers list their APIs for developers to discover
+  and integrate. Think RapidAPI, AWS Marketplace, or Stripe Apps.
+
+  Challenges:
+  - 50 API providers with vastly different documentation quality
+  - Developers need to compare APIs (functionality, pricing, reliability)
+  - Each provider wants to maintain their own documentation style
+  - Need consistent discovery experience while respecting provider identity
+  - Quality control: how to ensure minimum documentation standard
+  - Cross-API workflows: developers combine multiple marketplace APIs
+
+  Task: Design the documentation framework for the API marketplace.
+  Include: provider onboarding documentation requirements, documentation
+  templates and standards, discovery and comparison features, cross-API
+  integration guides, and quality scoring that ranks providers by
+  documentation quality.
+
+assertions:
+  - type: llm_judge
+    criteria: "Provider documentation standards ensure consistency — mandatory fields per listing: name, description (structured: what it does, who it's for, key features), OpenAPI 3.x spec, authentication method, pricing tiers, rate limits, SLA commitment, getting started guide (under 5 minutes). Standardized sections: Overview (templated), Authentication (templated), Endpoints (auto-generated from OpenAPI), Pricing (templated), Support (contact method, response time SLA). Template system: providers fill in structured templates — consistent presentation while allowing customization in descriptions and guides. Minimum quality gate: listing must score 70/100 on documentation quality rubric before going live. Provider documentation portal: where providers edit their listing with preview"
+    weight: 0.35
+    description: "Provider standards"
+  - type: llm_judge
+    criteria: "Discovery and comparison features help developers choose — category taxonomy: organized by function (payments, communications, data, AI/ML) with sub-categories. Comparison table: side-by-side view of up to 3 APIs showing features, pricing, rate limits, authentication method, SDK languages supported, documentation quality score. Search: full-text search across all API documentation, filter by category, authentication type, pricing model, language support. Developer reviews and ratings: per-provider DX rating (documentation quality, support responsiveness, reliability). 'Similar APIs' recommendations. Use case pages: 'Building an e-commerce platform? You'll need these APIs' — curated bundles. Playground: try any marketplace API directly from the listing page"
+    weight: 0.35
+    description: "Discovery features"
+  - type: llm_judge
+    criteria: "Cross-API documentation and quality scoring are strategic — cross-API integration guides: common workflows combining multiple marketplace APIs (e.g., 'Accept payments + send receipts: Payments API + Email API'). Unified authentication: marketplace SDK handles auth for all providers (one token, multiple APIs). Quality scoring rubric: documentation completeness (25%), accuracy (examples work) (25%), developer feedback (25%), maintenance (updated within 30 days of API changes) (25%). Score displayed on listing page — providers compete on documentation quality. Incentives: top-rated providers get featured placement, lower marketplace fees. Provider leaderboard: public ranking of documentation quality. Marketplace-level documentation: how to use the marketplace itself, unified SDK guide, billing documentation, support escalation paths"
+    weight: 0.30
+    description: "Cross-API and quality"

package/courses/api-documentation-writing/scenarios/level-5/board-api-strategy.yaml

@@ -0,0 +1,48 @@
+meta:
+  id: board-api-strategy
+  level: 5
+  course: api-documentation-writing
+  type: output
+  description: "Present API strategy to the board — translate technical API documentation investments into board-level business language covering ROI, competitive positioning, and growth enablement"
+  tags: [API, documentation, board-presentation, ROI, business-strategy, executive, master]
+
+state: {}
+
+trigger: |
+  The board meeting is next week. You need to present the case for
+  a $2M investment in developer documentation over the next 2 years.
+  Board members are not technical — they understand revenue, market
+  share, competitive positioning, and customer acquisition.
+
+  What they'll ask:
+  - "Why does documentation need $2M? Can't we just use AI to write it?"
+  - "What's the ROI? When do we see returns?"
+  - "Our competitor spends less on docs — why should we spend more?"
+  - "How does this compare to investing $2M in more sales reps?"
+  - "What happens if we don't invest in documentation?"
+
+  Data available:
+  - Current: 5,000 integrations, $50M ARR, 3.5% monthly churn
+  - Developer acquisition cost (DAC): $2,500 per integration
+  - Support cost: $50 per ticket, 3,000 doc-related tickets/year ($150K)
+  - Competitor A: invested $3M in docs, grew integrations 3x in 2 years
+  - Developer survey: 40% cite "documentation quality" in churn reasons
+
+  Task: Write the board presentation talking points. Include: executive
+  summary, investment case with financial model, competitive analysis,
+  risk of inaction, and comparison to alternative investments (sales
+  reps vs documentation).
+
+assertions:
+  - type: llm_judge
+    criteria: "Executive summary speaks business language — no technical jargon. Key message: documentation is customer acquisition infrastructure, not a cost center. Headlines: (1) documentation quality drives 40% of developer churn — fixing it protects $20M ARR at risk, (2) better documentation reduces developer acquisition cost from $2,500 to $800, (3) Competitor A's documentation investment correlated with 3x integration growth, (4) $2M investment projected to generate $15M incremental ARR over 2 years (7.5x ROI). Framing: this is not 'writing help pages' — this is building the customer onboarding and retention infrastructure that the developer business model requires. One-page summary with financials that a non-technical board member can absorb in 2 minutes"
+    weight: 0.35
+    description: "Executive summary"
+  - type: llm_judge
+    criteria: "Financial model is rigorous — investment: Year 1 $1M (team expansion, portal build, content creation), Year 2 $1M (continued content, internationalization, AI tools). Returns model: (1) Churn reduction: improving docs addresses 40% of churn, reducing monthly churn from 3.5% to 2.5% retains $5M additional ARR annually. (2) Acquisition efficiency: self-service documentation reduces DAC from $2,500 to $800, same sales budget onboards 3x more developers. (3) Support savings: reducing doc-related tickets by 70% saves $105K/year. (4) Conversion improvement: TTFC reduction from 5 days to 4 hours increases trial conversion by X%. Total 2-year impact: $15M+ incremental ARR. Payback period: under 12 months. Sensitivity analysis: even at 50% of projected impact, ROI exceeds 3x"
+    weight: 0.35
+    description: "Financial model"
+  - type: llm_judge
+    criteria: "Risk analysis and alternatives comparison are compelling — risk of inaction: 40% churn factor worsens as competitor docs improve, developer expectations rise annually, $20M ARR at risk over 2 years. Competitor comparison: Competitor A spent $3M and grew 3x — we're proposing $2M for similar trajectory. Alternative comparison: $2M in sales reps = 8 reps × $250K = ~800 new integrations at $2,500 DAC. $2M in documentation = infrastructure that supports unlimited onboarding at $800 DAC — scales better, compounds over time. Documentation is leverage on every other growth investment (marketing, sales, partnerships all benefit). AI and documentation: AI helps write and maintain docs (reducing cost) but doesn't replace strategy, design, or developer empathy. Timeline with decision urgency: every quarter delayed is $X in continued churn"
+    weight: 0.30
+    description: "Risk and alternatives"

package/courses/api-documentation-writing/scenarios/level-5/documentation-program-strategy.yaml

@@ -0,0 +1,42 @@
+meta:
+  id: documentation-program-strategy
+  level: 5
+  course: api-documentation-writing
+  type: output
+  description: "Design documentation program strategy — create a multi-year documentation program vision connecting developer experience to business outcomes across an API-first organization"
+  tags: [API, documentation, program-strategy, vision, business-outcomes, master]
+
+state: {}
+
+trigger: |
+  You're the VP of Developer Relations at an API-first company doing
+  $50M ARR. The board wants a 3-year strategy for the developer
+  documentation program. Context:
+
+  - 5,000 active integrations across 3 API products
+  - Developer ecosystem is the primary growth engine (80% of revenue)
+  - Current documentation team: 4 technical writers, 1 DX engineer
+  - Annual documentation budget: $800K (salaries + tooling)
+  - Competitor analysis: Stripe and Twilio set the standard — your docs
+    are rated "adequate" by developers
+  - Board goal: reach 15,000 integrations and $150M ARR in 3 years
+
+  Task: Present the 3-year documentation program strategy to the board.
+  Include: vision statement, year-by-year roadmap, team growth plan,
+  technology investments, competitive positioning, and how documentation
+  directly contributes to the $150M ARR target. Quantify the business
+  impact of every major initiative.
+
+assertions:
+  - type: llm_judge
+    criteria: "Vision connects documentation to revenue growth — clear thesis: documentation quality directly drives integration velocity, which drives revenue. Data: current TTFC of X days, each day reduced increases trial-to-paid conversion by Y%. Developer ecosystem economics: each integration generates $10K ARR average, reaching 15,000 integrations requires 10,000 new integrations in 3 years, documentation must support onboarding 300+ integrations/month vs current 100/month. Vision: evolve from 'documentation' to 'developer education platform' — not just reference docs but learning paths, certification, community-generated content. Competitive positioning: match Stripe quality in year 1, differentiate with AI-powered personalized documentation in year 2-3"
+    weight: 0.35
+    description: "Vision and revenue link"
+  - type: llm_judge
+    criteria: "Year-by-year roadmap is detailed and measurable — Year 1 (Foundation → Excellence): hire 2 more writers + 1 DX engineer, launch unified developer portal, implement docs-as-code, achieve Stripe-quality API reference, interactive explorer, 3 quickstart tutorials, automated testing. KPIs: TTFC from 5 days to 1 day, satisfaction from 6/10 to 8/10. Investment: $400K additional. Year 2 (Differentiation): multi-language docs (Japanese, Portuguese), SDK documentation for 6 languages, partner certification program, AI-powered search and recommendations, community contributions platform. KPIs: international integrations +200%, partner onboarding time -75%. Year 3 (Platform): developer education platform with courses, certification program generating revenue, AI documentation assistant (answers developer questions from docs), predictive documentation (auto-generate docs from code changes). Each initiative has estimated revenue impact"
+    weight: 0.35
+    description: "Roadmap"
+  - type: llm_judge
+    criteria: "Investment case and team plan are board-ready — total 3-year investment: $X (broken down by year, by category: people, tooling, content). ROI model: documentation investment → reduced TTFC → higher conversion → more integrations → more revenue. Specific calculations: reducing TTFC by 1 day increases conversion by X% = Y additional integrations × $10K ARR = $Z revenue. Support cost savings: reducing doc-related tickets by Z% saves $W/year. Team growth: Year 1 (7 people), Year 2 (10 people), Year 3 (12 people) — roles defined (writers, DX engineers, community manager, documentation PM). Technology investments justified: portal ($X, enables self-service), testing ($Y, prevents regression), AI ($Z, scales support). Risk mitigation: what if the investment doesn't hit targets — leading indicators to track quarterly, pivot strategies"
+    weight: 0.30
+    description: "Investment case"

package/courses/api-documentation-writing/scenarios/level-5/documentation-team-structure.yaml

@@ -0,0 +1,47 @@
+meta:
+  id: documentation-team-structure
+  level: 5
+  course: api-documentation-writing
+  type: output
+  description: "Design documentation team structure — define roles, responsibilities, career paths, and organizational placement for a developer documentation team at scale"
+  tags: [API, documentation, team-structure, hiring, career-path, organization, master]
+
+state: {}
+
+trigger: |
+  You're scaling from 2 technical writers to a 15-person documentation
+  team. You need to design the organizational structure from scratch:
+
+  Current state:
+  - 2 technical writers embedded in engineering (overwhelmed)
+  - 5 engineering teams with 15 APIs
+  - Growing from 5,000 to 20,000 integrations over 3 years
+  - Documentation quality varies wildly by product team
+  - No career path for technical writers (they all leave after 2 years)
+
+  Decisions to make:
+  - Centralized documentation team vs embedded per product team?
+  - What roles beyond "technical writer" are needed?
+  - Where does documentation report? Engineering? Product? Marketing?
+  - How do you hire for API documentation specifically?
+  - What does a career ladder look like?
+
+  Task: Design the complete documentation team structure. Include:
+  organizational model, role definitions, hiring profiles, career
+  ladder, and the collaboration model with engineering and product
+  teams. Address retention by making the team a place where people
+  build meaningful careers.
+
+assertions:
+  - type: llm_judge
+    criteria: "Organizational model balances consistency and responsiveness — recommend hybrid model: centralized documentation team for standards, tooling, and platform — with embedded 'documentation engineers' allocated to product teams for deep domain knowledge. Reporting: documentation team reports to VP of Developer Experience (not Engineering or Marketing — needs independence). Team structure: Director of Documentation → 3 pods: (1) Content (writers producing docs), (2) Platform (DX engineers building portal, tools, CI/CD), (3) Standards (style guide, quality, governance). Pod leads have management responsibilities. Cross-functional rituals: weekly sync with product teams, quarterly planning aligned with product roadmap. Justify why embedded-only fails (inconsistency) and centralized-only fails (slow, disconnected)"
+    weight: 0.35
+    description: "Organizational model"
+  - type: llm_judge
+    criteria: "Roles are differentiated beyond 'technical writer' — roles defined: (1) API Technical Writer: writes reference docs, guides, tutorials — strong writing + basic coding. (2) Documentation Engineer: builds documentation tooling, CI/CD, automated testing — strong coding + adequate writing. (3) Developer Experience Designer: designs information architecture, user journeys, portal UX — design + developer empathy. (4) Developer Educator: creates tutorials, videos, workshops — teaching + technical depth. (5) Documentation Program Manager: cross-team coordination, metrics, governance — project management + technical understanding. (6) Director of Documentation: strategy, team leadership, budget, executive communication. Hiring profiles: for API doc writers, prioritize candidates who have shipped code (bootcamp grad who learned to write > English major who learned to code). Interview process: writing sample with API context, pair writing session, technical assessment"
+    weight: 0.35
+    description: "Roles and hiring"
+  - type: llm_judge
+    criteria: "Career ladder and retention strategy are compelling — career levels: Junior Writer (L1) → Technical Writer (L2) → Senior Writer (L3) → Staff Writer (L4) → Principal Writer (L5). Parallel management track: Lead → Manager → Senior Manager → Director. Each level: clear expectations for scope, quality, impact, and independence. L1: write docs from detailed outlines. L3: own documentation for entire product, influence API design. L5: set documentation strategy across the organization. Growth opportunities: specialize (API design, developer education, tooling) or generalize (management, strategy). Retention strategies: competitive compensation benchmarked against software engineers (not content writers), conference speaking opportunities, open-source contribution time, documentation innovation projects (AI tools, interactive docs). Address why writers leave: no career growth (ladder fixes this), undervalued (executive reporting and metrics fix this), isolated (team structure and community fix this)"
+    weight: 0.30
+    description: "Career ladder"

package/courses/api-documentation-writing/scenarios/level-5/dx-competitive-advantage.yaml

@@ -0,0 +1,46 @@
+meta:
+  id: dx-competitive-advantage
+  level: 5
+  course: api-documentation-writing
+  type: output
+  description: "Position developer experience as competitive advantage — articulate how superior API documentation creates defensible competitive moats and drives market leadership"
+  tags: [API, documentation, developer-experience, competitive-advantage, moat, strategy, master]
+
+state: {}
+
+trigger: |
+  Your API competes in a commoditized market — three competitors offer
+  nearly identical functionality at similar prices. The differentiation
+  is developer experience:
+
+  - Competitor A: best docs, 40% market share, highest developer love
+  - Competitor B: cheapest, 35% market share, "good enough" docs
+  - You: 25% market share, technically superior API but poor DX
+
+  Board question: "We have the best technology but are losing to
+  Competitor A. Their developers love them. How do we win developers?"
+
+  Evidence that DX matters:
+  - 73% of developers say documentation quality influences API choice
+  - Switching cost for APIs is low — developers migrate in weeks
+  - Developer advocacy drives organic growth (word of mouth)
+  - Best-documented APIs command 20-30% price premium
+
+  Task: Present a strategy to make developer experience your primary
+  competitive differentiator. Include: competitive analysis framework,
+  DX improvement roadmap, measurement methodology, and how to build
+  a developer community that becomes a growth engine.
+
+assertions:
+  - type: llm_judge
+    criteria: "Competitive analysis is data-driven — framework for evaluating DX: (1) time to first API call, (2) time to production integration, (3) documentation completeness and accuracy, (4) error message helpfulness, (5) SDK quality, (6) community and support responsiveness, (7) developer satisfaction (NPS). Benchmark against Competitor A on each dimension with specific scores. Identify DX gaps: where are developers struggling more with your API than Competitor A? Developer journey mapping: compare end-to-end experience (discovery → evaluation → integration → production → growth). Win/loss analysis: interview developers who chose Competitor A — what specifically drove their decision? Quantify: each DX improvement point translates to X% market share shift"
+    weight: 0.35
+    description: "Competitive analysis"
+  - type: llm_judge
+    criteria: "DX improvement roadmap creates measurable differentiation — phased approach: Phase 1 (parity, 0-6 months): match Competitor A's documentation quality, reduce TTFC to industry best, fix top 10 developer pain points. Phase 2 (differentiation, 6-18 months): interactive tutorials, personalized onboarding paths, AI-powered documentation search, multi-language support, community-generated examples. Phase 3 (leadership, 18-36 months): developer education platform, certification program, API design toolkit for customers building on your platform, developer conference. Each phase has measurable DX metrics with targets. Quick wins: identify 5 things Competitor A does poorly — leapfrog on those immediately. Investment required per phase with expected market share impact"
+    weight: 0.35
+    description: "DX roadmap"
+  - type: llm_judge
+    criteria: "Community strategy creates sustainable growth moat — developer community as growth engine: developer advocates → content creation → organic discovery → new developers. Community program: Stack Overflow presence, GitHub open-source tools, developer blog with technical content, conference talks, local meetups. User-generated content: community-maintained code examples, integration guides, tutorials — scales documentation beyond your team. Developer champions program: identify and empower your most active developers with early access, swag, speaking opportunities. Measurement: community-influenced signups (developers who engaged with community before signing up), community content views, Net Promoter Score trend. Moat: strong developer community is hard for competitors to replicate — it takes years to build trust and relationships. Economic model: community reduces CAC (customer acquisition cost) and increases retention"
+    weight: 0.30
+    description: "Community strategy"

package/courses/api-documentation-writing/scenarios/level-5/ecosystem-documentation.yaml

@@ -0,0 +1,45 @@
+meta:
+  id: ecosystem-documentation
+  level: 5
+  course: api-documentation-writing
+  type: output
+  description: "Document developer ecosystem — create documentation strategy for a platform ecosystem including APIs, SDKs, plugins, integrations, and community-built extensions"
+  tags: [API, documentation, ecosystem, platform, extensions, plugins, community, master]
+
+state: {}
+
+trigger: |
+  Your platform has evolved into an ecosystem:
+
+  - Core APIs: 3 products (payments, billing, identity) — 200 endpoints
+  - SDKs: 6 languages (Python, Node.js, Go, Java, Ruby, PHP)
+  - Plugins: 30 official integrations (Shopify, WordPress, Salesforce...)
+  - Extensions: 200 community-built extensions in a marketplace
+  - Webhooks: 50 event types across all products
+  - CLI tool for developer workflows
+  - Terraform provider for infrastructure-as-code
+
+  Documentation challenge: interconnected systems where changes cascade.
+  A payments API update affects SDKs, plugins, extensions, and guides
+  simultaneously. No one person understands the full documentation
+  surface area.
+
+  Task: Design the documentation strategy for the entire ecosystem.
+  Include: content architecture for interconnected products, cross-
+  product documentation (how products work together), contributor
+  documentation for community extension builders, and a coordination
+  model for keeping everything in sync when core APIs change.
+
+assertions:
+  - type: llm_judge
+    criteria: "Ecosystem architecture manages complexity — content hierarchy: platform overview (how products relate) → product docs (per-product deep dive) → SDK docs (per-language) → integration docs (per-platform) → extension docs (community). Cross-referencing: every product page links to related products, relevant SDKs, and applicable integrations. Unified navigation: single search across all documentation, consistent sidebar, breadcrumbs showing product > section > page. Information architecture: developer-centric (task-based: 'Accept a payment') not organization-centric (product team structure). Shared components: authentication, error handling, pagination documented once, referenced everywhere. Monorepo vs multi-repo documentation strategy with justification"
+    weight: 0.35
+    description: "Ecosystem architecture"
+  - type: llm_judge
+    criteria: "Cross-product and extension documentation enable the ecosystem — cross-product guides: 'Accept payment and auto-generate invoice' (payments + billing), 'Authenticate user and create customer' (identity + payments). These guides are the highest-value content — they show the ecosystem advantage. Extension builder documentation: API reference for extension points, plugin development guide (scaffolding, testing, publishing), code review requirements, marketplace listing guidelines, versioning policy for extension APIs. Community documentation: contributor guide, documentation style guide for extension authors, templates for extension docs, quality review process. Extension documentation is part of the marketplace listing"
+    weight: 0.35
+    description: "Cross-product and extensions"
+  - type: llm_judge
+    criteria: "Coordination model keeps ecosystem docs in sync — change propagation: when core API changes, automated system identifies affected: SDKs (which methods use this endpoint), plugins (which integrations call this), guides (which tutorials reference this), extensions (which extension APIs are impacted). Notification: affected teams/maintainers notified with specific impact. SDK update automation: OpenAPI spec change triggers SDK regeneration and doc update. Plugin compatibility matrix: table showing which plugin versions work with which API versions. Community notification: breaking changes announced in developer forum, extension authors notified via email. Documentation ownership model: core team owns product docs, SDK teams own SDK docs, integration team owns plugin docs, community owns extension docs — with platform team providing templates and quality oversight. Quarterly ecosystem documentation review: cross-team sync on upcoming changes"
+    weight: 0.30
+    description: "Coordination model"

package/courses/api-documentation-writing/scenarios/level-5/industry-documentation-patterns.yaml

@@ -0,0 +1,46 @@
+meta:
+  id: industry-documentation-patterns
+  level: 5
+  course: api-documentation-writing
+  type: output
+  description: "Analyze industry documentation patterns — evaluate and synthesize documentation best practices from leading API companies to define next-generation documentation standards"
+  tags: [API, documentation, industry-patterns, best-practices, benchmarking, standards, master]
+
+state: {}
+
+trigger: |
+  You're writing a keynote talk for a developer relations conference:
+  "The Future of API Documentation." You need to analyze what the best
+  API companies do, identify patterns, and articulate where the industry
+  is heading.
+
+  Companies to analyze:
+  - Stripe: gold standard for API docs, interactive examples
+  - Twilio: code-first documentation, multi-language examples
+  - GitHub: massive API surface, excellent guides alongside reference
+  - Cloudflare: developer-friendly docs for complex infrastructure
+  - Plaid: security-sensitive API with excellent onboarding
+  - OpenAI: rapidly evolving API with streaming and novel patterns
+
+  Each has solved different documentation challenges. The audience
+  wants actionable insights they can apply to their own APIs.
+
+  Task: Write the keynote content analyzing documentation patterns
+  across these companies. Identify: common patterns (what they all do),
+  differentiating innovations (unique approaches), emerging trends,
+  and a framework for evaluating and improving API documentation
+  that any company can apply.
+
+assertions:
+  - type: llm_judge
+    criteria: "Analysis identifies common patterns across leaders — patterns every great API doc has: (1) time-to-first-call under 5 minutes (all have quickstart), (2) interactive code examples (not just static snippets), (3) consistent error documentation (every error explained), (4) authentication documented with copy-paste examples, (5) changelog with structured change categories, (6) sandbox/test mode prominently featured, (7) search that works (semantic, not just keyword). Anti-patterns found in poor docs: auto-generated Swagger with no descriptions, examples with placeholder data (foo, bar, 123), inconsistent formatting, no getting started guide. Framework: score any API documentation on these patterns (1-5 per dimension) for quick assessment"
+    weight: 0.35
+    description: "Common patterns"
+  - type: llm_judge
+    criteria: "Company-specific innovations are insightful — Stripe: progressive disclosure (simple by default, expandable for complexity), right-sidebar code examples that update when toggling languages, inline 'test mode' toggle. Twilio: code-first approach (show code before explaining concepts), helper libraries for every language, 'TwiML' documentation as domain-specific language docs. GitHub: massive reference managed through automated tooling, 'Getting started' guides for common workflows, GraphQL + REST documentation coexistence. Cloudflare: infrastructure docs that explain concepts before API calls, Wrangler CLI docs integrated with API docs. Plaid: Link (pre-built UI) documentation alongside raw API, security-conscious docs (never show real credentials, even in examples). OpenAI: streaming API documentation, novel patterns (tool use, function calling) requiring new documentation paradigms. Each insight is specific enough to be actionable"
+    weight: 0.35
+    description: "Company innovations"
+  - type: llm_judge
+    criteria: "Emerging trends and evaluation framework are forward-looking — trends: (1) AI-assisted documentation (chatbots answering API questions, AI-generated examples), (2) personalized documentation (adapt to developer's language, framework, skill level), (3) video and interactive tutorials alongside text, (4) documentation as part of the product (not separate site), (5) community-contributed documentation at scale, (6) API documentation for AI consumers (not just human developers — how do LLMs read your docs?). Evaluation framework: 5 dimensions — Discoverability (can developers find what they need?), Completeness (is everything documented?), Accuracy (do examples work?), Usability (can a new developer integrate in 30 minutes?), Maintenance (are docs kept current?). Each dimension: 5-point rubric with specific criteria. Framework applicable to any API, any size company. Action items: top 3 things any company can do this quarter to improve their docs"
+    weight: 0.30
+    description: "Trends and framework"

package/courses/api-documentation-writing/scenarios/level-5/master-documentation-shift.yaml

@@ -0,0 +1,46 @@
+meta:
+  id: master-documentation-shift
+  level: 5
+  course: api-documentation-writing
+  type: output
+  description: "Combined master shift — present a complete API documentation transformation strategy for an enterprise acquiring a developer platform company, unifying two documentation ecosystems"
+  tags: [API, documentation, combined, shift-simulation, M&A, transformation, master]
+
+state: {}
+
+trigger: |
+  Your enterprise (FinCorp, $500M revenue, traditional financial services)
+  just acquired a developer platform startup (DevPay, $30M ARR, 8,000
+  integrations, beloved by developers). You're now responsible for unifying
+  the documentation strategy.
+
+  The situation:
+  - FinCorp: enterprise docs (PDFs, Confluence), SOAP APIs, no developer portal
+  - DevPay: beautiful developer portal, REST APIs, OpenAPI specs, community
+  - FinCorp developers: banks and large enterprises, expect formal docs
+  - DevPay developers: startups and indie devs, expect Stripe-quality DX
+  - Goal: unified platform offering both enterprise and developer APIs
+  - Risk: DevPay developers leave if documentation quality degrades
+  - Opportunity: FinCorp's 500 enterprise clients gain modern API access
+
+  Timeline: 18 months to unified platform. Board is watching.
+
+  Task: Present the complete M&A documentation strategy. Cover:
+  assessment of both documentation estates, unified platform vision,
+  migration plan preserving DevPay's DX quality while adding FinCorp's
+  enterprise requirements, team integration, technology consolidation,
+  and risk mitigation. This is a board-level strategy document.
+
+assertions:
+  - type: llm_judge
+    criteria: "Assessment and vision bridge two worlds — dual assessment: DevPay docs (strengths: interactive explorer, modern portal, community, developer love. Gaps: no enterprise compliance docs, no SOAP). FinCorp docs (strengths: compliance documentation, enterprise onboarding. Gaps: no developer portal, outdated tech, terrible DX). Unified vision: 'One platform, two experiences' — modern developer portal (DevPay standard) with enterprise documentation layer (compliance, SLA, security whitepapers). Not: force FinCorp enterprise style on DevPay developers. Not: ignore enterprise requirements. Technology: adopt DevPay's portal as foundation, add enterprise features. Brand: unified brand with clear signposting for enterprise vs developer audiences"
+    weight: 0.35
+    description: "Assessment and vision"
+  - type: llm_judge
+    criteria: "Migration plan preserves what works — phase 1 (months 1-6): protect DevPay DX (do not change anything DevPay developers currently use), add FinCorp APIs to DevPay portal with proper documentation, begin migrating FinCorp enterprise docs to modern format. Phase 2 (months 7-12): unified authentication documentation, cross-product guides (FinCorp + DevPay), enterprise compliance section added to portal, SOAP-to-REST migration guides for FinCorp customers. Phase 3 (months 13-18): fully unified portal, deprecated legacy FinCorp docs, community migrated, enterprise customers onboarded. Key risk: DevPay developer churn during transition — mitigation: DevPay documentation team retains autonomy during phase 1, changes are additive only, developer advisory board provides feedback before any changes. Success metric: DevPay NPS stays above 50 throughout transition"
+    weight: 0.35
+    description: "Migration plan"
+  - type: llm_judge
+    criteria: "Team integration and board communication are strategic — team structure: DevPay documentation team leads unified team (they have the skills), FinCorp technical writers retrained on modern tools (docs-as-code, OpenAPI, portal). Org chart: combined team of 12 under Head of Developer Documentation (hire from DevPay or external). Training: 3-month ramp for FinCorp writers on DevPay tools and standards. Attrition plan: expected to lose some writers during transition — pre-identified backfill candidates. Board communication: quarterly progress report with metrics — developer satisfaction (both audiences), documentation coverage, migration percentage complete, developer churn rate. Budget: $1.5M over 18 months (team, tooling, migration). Risk register: top 5 risks with mitigations (DevPay developer churn, FinCorp enterprise customer confusion, team culture clash, technical debt, timeline slip). Success criteria: unified portal live, both audiences satisfied (NPS > 40), zero documentation-related churn"
+    weight: 0.30
+    description: "Team and board"

package/courses/code-review-feedback-writing/course.yaml

@@ -0,0 +1,12 @@
+id: code-review-feedback-writing
+name: "Code Review Feedback Writing"
+description: >
+  Master code review feedback writing from clear inline comments and
+  constructive tone to organizational review culture design and
+  engineering quality strategy. Progress through giving actionable
+  feedback, reviewing complex changes across domains, mentoring
+  through reviews, optimizing review processes, and building review
+  cultures that accelerate engineering organizations.
+levels: 5
+scenarios_per_level: 10
+tags: [writing, code-review, feedback, engineering, collaboration, mentoring, quality]