Skip to main content
Version: Next

Documentation Roadmap (Structure + Pattern)

This roadmap defines how we structure and write documentation so it stays consistent, scalable, and versionable.

1) The documentation system (not a blog)​

We are end-user only for now. The docs focus on workflows, screens, permissions, and troubleshooting.

Rule: User docs never expose backend internals (services, databases, queues, auth internals).

Developer docs are intentionally deferred until end-user coverage is complete.

2) Information architecture (IA)​

User docs are organized by how schools operate, not by how engineers build.

User Docs top-level sections​

  1. Overview
    • What the platform is
    • What’s new (release notes)
  2. Concepts (mental models)
    • Definitions and relationships (schools, academic years, invoices/payments, roles)
  3. Getting Started
    • First 30–60 minutes to value (setup + first end-to-end workflow)
  4. Guides (workflows)
    • Goal-based, step-by-step procedures
  5. Modules (reference)
    • Screen-by-screen reference (fields, actions, rules)
  6. Security & Access
    • Identity & access, security sessions/MFA, and audit guidance
  7. Troubleshooting & FAQs
    • Error explanations, common problems, known workarounds
  8. Release Notes (user impact only)
    • Changes users feel + what to do

Developer docs​

Deferred. We will re-introduce internal documentation only after end-user docs are complete.

3) System sources of truth (non-negotiable)​

Docs are system-driven. We only document what exists in the product.

Primary sources:

  • Navigation + labels: src/config/navigation.ts and src/hooks/use-breadcrumbs.ts
  • Tenant route structure: src/app/(tenants)/[tenant]/...
  • Domain capabilities and API modules: src/lib/api/domains/*

Reference page: App navigation (source of truth)

In-app links are documented in In-app help links.

4) Folder structure (canonical)​

All docs live in docusaurus/.

  • docusaurus/docs/ → User Docs (route /)
  • docusaurus/developers/ → Reserved for later (not active yet)

Within user docs, create folders that match the IA above:

  • overview/
  • concepts/
  • getting-started/
  • guides/
  • modules/
  • roles-permissions/ (labeled Security & Access)
  • troubleshooting/
  • release-notes/

Each folder has a _category_.json that sets label + ordering.

5) Page patterns (templates)​

We use repeatable templates so docs stay predictable.

A) Workflow page template (Guides)​

Every workflow page includes:

  • Goal (one sentence)
  • Before you start (prereqs + required permissions)
  • Steps (numbered; UI labels match the product)
  • Result (what success looks like)
  • Common mistakes (top 3–7)
  • Related pages

B) Screen reference template (Modules)​

Every module page includes:

  • Purpose (when to use it)
  • Navigation path (where to find it)
  • Primary actions (Create/Edit/Delete/Export)
  • Field reference (table: Field → Meaning → Required → Notes)
  • Rules & validations
  • Permissions (who can do what)
  • FAQs

C) Concept page template​

Every concept page includes:

  • Definition (plain language)
  • Why it matters
  • How it connects (related concepts)
  • Common misunderstandings

D) Troubleshooting page template​

  • Symptom
  • Likely causes
  • Fix steps
  • What to send support (screenshots / IDs)

6) Naming conventions​

  • File names: kebab-case (e.g. record-a-payment.mdx)
  • Titles: sentence case (e.g. “Record a payment”)
  • One page = one purpose
  • Avoid “misc”, “notes”, “random”, “v2”

7) Versioning policy (non-negotiable)​

We version documentation because product behavior changes.

  • Use npm run docs:version -- <product-version> (example: 0.1.0).
  • Changes that alter UI behavior must update docs in the same PR.
  • Release notes must be user impact only (no internal refactors).

8) Ownership and quality gates​

Required review checklist (every docs PR)​

  • Written for the correct audience (user vs developer)
  • No backend internals in User Docs
  • Workflow pages include prerequisites + permissions
  • Module pages include field reference + validations
  • Screenshots match current UI (or intentionally omitted)
  • Links don’t break (npm run docs:build passes)

Definition of Done (DoD)​

A section is “done” when:

  • The main workflows exist for that area
  • Each referenced screen has a module page
  • Permissions are documented
  • Top FAQs / errors are covered

9) Execution plan (phases)​

Phase 0 — Skeleton (1 day)​

  • Create all folders + _category_.json
  • Add empty stub pages for the whole IA
  • Add templates as reusable patterns

Phase 1 — First user journey (1–2 weeks)​

Focus on the 5 workflows that reduce tickets fastest:

  1. Onboard a school
  2. Add a student
  3. Bulk import students (CSV)
  4. Create invoice / fee setup
  5. Record payment + issue receipt

Phase 2 — Reference coverage (2–4 weeks)​

  • Module pages for all screens touched in Phase 1
  • Security & Access: identity & access, security controls, common access issues

Phase 3 — Expansion (ongoing)​

  • Admissions, exams, attendance, notifications, analytics
  • Release notes discipline
  • Add screenshots + short clips where it reduces confusion

If you want, I can now scaffold the full folder tree + stub pages (Phase 0) so the structure is locked before writing content.