Appearance
Documentation roadmap
This page describes how these docs are organised and the principles behind them. It is for whoever maintains the documentation.
Goal
Explain Index Insure as one product (what it does and how to use it) for the people who operate it, without assuming any engineering background. The docs deliberately avoid implementation detail (how the frontend or the API is built); they describe the product as a whole.
Audience layers
The site is layered so each reader can enter at the right level:
- Understanding Index Insure: orientation for anyone (stakeholders, new joiners, clients).
- How it works: the drought-to-payout model and methodology (analysts, underwriters).
- Using Index Insure: task-based guides for operating each capability.
- Reference: the glossary.
Information architecture
docs/
├── index.md Home
├── introduction/ Understanding Index Insure
│ ├── what-is-index-insure.md
│ ├── how-index-insurance-works.md
│ ├── the-journey.md The data→payout story
│ └── roles-and-access.md Who uses it & access
├── concepts/ How it works
│ ├── projects.md
│ ├── units-of-insurance.md Areas / UAIs
│ ├── the-drought-signals.md NDVI + rainfall + soil moisture + drought index
│ ├── from-signals-to-index.md Baselines, scores, percentiles
│ ├── triggers-and-payouts.md
│ ├── pricing-the-risk.md The premium build-up (kept rigorous)
│ └── data-you-can-trust.md Governance, lineage, automatic ingestion, audit
├── guides/ Using Index Insure (capability-based)
│ ├── dashboard-overview.md Project dashboard (live)
│ ├── set-up-a-project.md
│ ├── manage-areas.md
│ ├── manage-data-sources.md
│ ├── run-analysis.md
│ ├── explore-results.md Map + report workspace
│ ├── insurance-setup.md Product, insured livestock, exposure basis
│ ├── price-a-product.md
│ ├── create-quotes.md
│ ├── policyholders.md The register (replaced the mock "Clients")
│ ├── payouts.md Payout runs, methods, gateways
│ ├── messaging.md Broadcasts, templates, SMS providers
│ ├── manage-your-team.md (Administration)
│ ├── review-audit-log.md (Administration)
│ └── training-courses.md (Administration; still sample data)
└── reference/
├── glossary.md
└── documentation-roadmap.md This pageWriting principles
- Product, not implementation. Describe what the platform does and how to use it. Do not reference routes/URLs, permission strings, data field names, frameworks, or API mechanics. Name areas of the app in plain words ("the data sources area"), not by route.
- One product, as a whole. Treat Index Insure as a single product, not a frontend plus a backend. Capabilities are described from the user's point of view.
- Capability-based guides. Each guide is a task ("Run an analysis", "Price a product"): what you do, how it works, what you see, and how to recover when something's off.
- Methodology stays rigorous. The insurance/index methodology (baselines, scores, the payout curve, the premium build-up with its worked example) is domain content and is kept in full, only software field-names are removed.
- Document what exists, as is. Describe the current state honestly. Where a capability runs on sample data today (the dashboard, clients, messaging, payouts, training), say so plainly rather than promising future behaviour.
- One vocabulary. Define a term once in the glossary and link to it.
- Stable links. Clean URLs are on: link without the
.mdextension.
Page templates
Concept page: one-paragraph definition → why it matters / where it sits in the journey → the mechanics (with a worked example or diagram) → "where to go next".
Guide page: what this capability is for → prerequisites → the key tasks as steps → what you see → troubleshooting → related.
Running the docs
From the project directory:
bash
yarn docs:dev # local dev server with hot reload
yarn docs:build # production build
yarn docs:preview # preview the production buildKeeping it current
When the product changes, update the affected page in the same change. As the operations capabilities (clients, messaging, payouts) move from sample data to live data, update their guides and remove the "sample data" notes. As the climate signals reach full coverage, soften the "expected-but-not-universal" notes in The drought signals and Data you can trust.