# VibeBlocks Documentation Structure Proposal

## Purpose

Define a clear, role-based documentation structure that is easy to navigate for:

- New users (onboarding through tutorials and examples)
- Advanced users (quick reference and glossary)
- Contributors and maintainers (bugs, pull requests, contribution workflow)

This proposal describes structure only. It does not rewrite existing content.

## Recommended Top-Level Navigation

1. Home
2. Start Here
3. Onboarding (New Users)
4. How-to Guides
5. Core Concepts
6. Quick Reference
7. API Reference
8. Glossary
9. Development and Contribution
10. Changelog and Migration Notes

## Documentation Information Architecture (Tree)

```text
docs/
  source/
    index.rst                         # Home
    start_here.md                     # Persona-based entry points

    onboarding/
      index.md                        # Onboarding path overview
      install-and-first-workflow.md
      user-onboarding-workflow.md
      failure-retry-compensation.md
      execution-flow-diagrams.md

    guides/
      index.md
      tasks-processes-workflows.md
      sync-vs-async-runner.md
      context-serialization.md
      recipes.md

    concepts/
      index.md
      architecture.md
      execution-model.md
      failure-strategies.md
      recommended-patterns.md

    reference/
      quick-reference.md              # Short, practical lookup
      api_reference.rst               # Full autogenerated reference

    glossary.md

    development/
      index.md
      setup.md
      bug-management.md               # Report -> triage -> fix -> test
      pull-request-workflow.md
      issue-and-pr-templates.md

    changelog-and-migrations.md
```

## Navigation Diagram

```text
VibeBlocks Documentation
|- Home
|- Start Here
|- Onboarding
|  |- Tutorials
|  |- Examples
|  `- Execution Diagrams
|- How-to Guides
|- Core Concepts
|- Quick Reference
|- API Reference
|- Glossary
|- Development and Contribution
|  |- Bug Workflow
|  |- PR Workflow
|  `- Contribution Standards
`- Changelog and Migration Notes
```

## Role-Based Entry Points

### New users

- Start Here -> Onboarding tutorials
- Focus: install, first workflow, practical examples, visual execution flow

### Advanced users

- Start Here -> Quick Reference + Glossary
- Focus: high-speed lookup, short examples, API shortcuts

### Contributors and maintainers

- Start Here -> Development and Contribution
- Focus: bug lifecycle, PR process, quality gates, review checklist

## Suggested Menu Labels (Exact Wording)

- Home
- Start Here
- Onboarding
- How-to Guides
- Core Concepts
- Quick Reference
- API Reference
- Glossary
- Development and Contribution
- Changelog and Migration Notes