Human Docs Generator Skill

Purpose

Creates role-based documentation after each sprint/milestone to ensure human understanding and knowledge transfer. Documentation is concise, visual, and actionable.

Tier

Tier 2-3 - Growth to Scale

Documentation Structure

1. Knowledge Section (Living Documents)

knowledge_docs:
  - quickstart.md: Get running in 5 minutes
  - architecture.md: System design with diagrams
  - api-reference.md: Endpoint documentation
  - data-flow.md: How data moves through system
  - deployment.md: How to deploy changes

2. Quiz Section (By Role and Level)

quizzes:
  developer_junior:
    - basics: "What is the main API endpoint?"
    - setup: "How do you run tests locally?"
    - git: "What's our branching strategy?"

  developer_senior:
    - architecture: "Explain the service layer pattern"
    - performance: "How do we handle caching?"
    - security: "What authentication method do we use?"

  architect:
    - decisions: "Why did we choose PostgreSQL?"
    - patterns: "Which design patterns are used?"
    - scaling: "How does the system scale?"

  marketing:
    - features: "What are the key differentiators?"
    - benefits: "How does this solve user problems?"
    - metrics: "What KPIs do we track?"

3. Demo Section

demo_materials:
  internal_pitch:
    - problem: "What problem are we solving?"
    - solution: "How our product solves it"
    - demo_flow: "Step-by-step demonstration"
    - metrics: "Success metrics"

  external_pitch:
    - hook: "Attention-grabbing opening"
    - pain_points: "Customer problems"
    - solution: "Our unique approach"
    - proof: "Case studies and results"

  claude_context:
    - questions: "Questions to ask Claude Code"
    - context_files: "Key files to reference"
    - common_tasks: "Frequent operations"

Mermaid Diagrams

System Architecture

graph TB
    User[User] --> Frontend[React Frontend]
    Frontend --> API[Django API]
    API --> DB[(PostgreSQL)]
    API --> Cache[(Redis)]
    API --> Queue[Celery Queue]

Data Flow

sequenceDiagram
    participant U as User
    participant F as Frontend
    participant A as API
    participant D as Database

    U->>F: Submit Payment
    F->>A: POST /payments
    A->>D: Save Transaction
    D-->>A: Transaction ID
    A-->>F: Success Response
    F-->>U: Confirmation

Documentation Style Guide

• Direct and concise - No fluff
• Visual first - Diagrams over text
• Action-oriented - How to do X
• Role-specific - Tailored content
• Living documents - Updated with changes

Output Structure

ai-state/human-docs/
├── knowledge/
│   ├── quickstart.md
│   ├── architecture.md
│   └── api-reference.md
├── quizzes/
│   ├── developer-junior.md
│   ├── developer-senior.md
│   └── architect.md
└── demos/
    ├── internal-pitch.md
    ├── external-pitch.md
    └── claude-context.md