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)

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

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