Docs Information Architecture

Why this now

We want the docs experience quality of products like turbostarter.dev/docs, but optimized for Athas internal delivery speed first.

Target shape

Two documentation tracks:

1. Internal track (default for team)

   • Runbooks, architecture decisions, operations, implementation playbooks.
   • Deep references and workflow details.

2. External track (later/public-ready)

   • Productized starter docs, onboarding paths, curated guides.
   • Reduced internal operational details.

Near-term implementation strategy

• Keep /docs focused on external-ready starter documentation.
• Introduce a dedicated internal docs navigation model and page grouping conventions.
• Start tagging docs by audience intent:
  • internal
  • external-ready
  • shared

Current implementation:

• /docs remains the external-ready canonical track.
• /internal is now active for operational runbook-first internal documentation.

Proposed IA layers

• Layer 1: Start Here (onboarding, development flow)
• Layer 2: Build (guides, package docs, scaffolding)
• Layer 3: Operate (runbooks, incident/secrets/purchase operations)
• Layer 4: Govern (ADRs, projection policy, standards)

Delivery phases

1. Phase A (current): internal docs quality and coverage completion.
2. Phase B: route and navigation split for internal/external views.
3. Phase C: publishable external docs surface with stable docs API.

Success criteria

• Team can find operational guidance within two navigation steps.
• External-facing docs can be generated without exposing internal-only runbooks.
• Documentation updates stay synchronized with roadmap and ADR status.