Skip to main content
Version: Next

Documentation System Outline (End Users)

This page is the contract for end-user documentation.

  • Audience: school admins, teachers, accountants, operators (non-technical)
  • Goal: reduce confusion, training time, and support tickets
  • Non-goal: explain backend architecture, services, databases, queues, auth internals

Writing rules (non-negotiable)​

  1. Use product language, not engineering language
    • Say “Sign in” not “JWT”, “session”, “token refresh”.
  2. Describe interfaces and outcomes
    • What users do, what they see, what the system changes.
  3. Every page must answer:
    • What is this? When should I use it? How do I do it? What can go wrong?
  4. Prefer workflows over features
    • Users think in goals (“record a payment”), not modules.
  5. Every module page includes:
    • Purpose → where to find it → field reference → common mistakes → permissions.

Information architecture (system, not blog)​

These sections are ordered to match how real schools onboard and operate.

1) Overview​

  • What Makronexus Education is
  • What problems it solves
  • What’s included (high-level modules)

2) Concepts (mental models)​

Users need the “map in their head”. Define nouns and relationships.

  • Tenants / workspaces (if exposed), schools, branches/campuses
  • Academic years, terms, classes, streams
  • Students, guardians, staff
  • Fees: invoices, payments, balances, receipts
  • Security & access (roles, permissions, sessions, audit)
  • Reports: source of truth, filters, export formats

3) Getting Started​

Fast path to value (first 30–60 minutes).

  • Access the system
  • Set up the school profile
  • Create academic structure
  • Create users + roles
  • Confirm you can complete a core flow end-to-end

4) Guides (goal-based workflows)​

These are the pages most users will read.

  • Onboard a new school
  • Add students (single + bulk import)
  • Record payments and reconcile
  • Promote students / rollover academic year
  • Generate common reports
  • Manage staff and access

5) Modules (screen-by-screen reference)​

This is not marketing; it’s reference. For each module:

  • What it is
  • Where it lives in the UI
  • Core actions
  • Field definitions
  • Validation rules
  • Edge cases
  • Permissions

6) Security & Access​

This is where “why is the button disabled?” is solved.

  • Identity & access (roles, permissions, policies)
  • Security (sessions, trusted devices, MFA)
  • Audit & compliance (logs, alerts, retention)

7) Troubleshooting & FAQs​

  • Common errors explained in plain language
  • Data issues (duplicates, missing records)
  • Imports and exports
  • Performance / “it’s slow” checklist

8) Release Notes (user-impact only)​

  • What changed
  • What users need to do
  • Known issues / workarounds

Page templates​

Workflow page template (Guides)​

  • Goal
  • Before you start (prereqs + permissions)
  • Steps (numbered, UI labels match the product)
  • Result (what success looks like)
  • Common mistakes
  • Related pages

Reference page template (Modules)​

  • Purpose
  • Navigation path
  • Actions (Create/Edit/Delete/Export)
  • Field reference
  • Rules & validations
  • Permissions
  • FAQs

Proposed end-user doc tree​

Use this tree as the backbone for all content.

  • Overview
    • What Makronexus Education does
    • What’s new (Release notes)
  • Concepts
    • Schools, branches, and access
    • Academic structure (years, terms, classes)
    • People (students, guardians, staff)
    • Finance concepts (invoices, payments, balances)
    • Permissions model (roles vs permissions)
  • Getting Started
    • Sign in and first-time access
    • Initial school setup checklist
    • Create academic year and term
    • Add your first student
    • Record your first payment
  • Guides
    • School onboarding workflow
    • Student admission workflow
    • Bulk import students (CSV)
    • Fee setup and invoicing
    • Record payment and issue receipt
    • Refunds / reversals (if supported)
    • Attendance workflow (if supported)
    • Exams workflow (if supported)
    • End-of-term / end-of-year rollover
  • Modules
    • Dashboard
    • Students
    • Admissions
    • Classes & Academics
    • Fees & Billing
    • Payments
    • Reports
    • Staff & Users
    • Settings
  • Security & Access
    • Security & access overview
    • Security & access troubleshooting
  • Troubleshooting & FAQs
    • Can’t sign in
    • Missing buttons / access denied
    • CSV import errors
    • Reports don’t match expectations
    • Receipts and audit trail questions

Versioning policy​

  • Docs are versioned because behavior changes over time.
  • Every UI-breaking change requires docs updates in the same release.
  • Version names should match your product releases (e.g. 0.1.0, 0.2.0).

Next: this outline becomes the set of Docusaurus pages and categories.