Maintaining the Docs
These rules keep the documentation in step with the product. They apply to anyone who changes BillHive behaviour.
When you ship a change
Update everything the change touches, in the same pull request as the code:
| What changed | Update |
|---|---|
| A screen, field, button or validation | The user manual page for that module |
| How a business process behaves (billing, proration, renewals) | The matching Knowledge Base page and any Workflow diagram |
| An endpoint, payload or event | API Reference (generated), Pricing v2 API or Webhook |
| Something users will ask about | FAQ or the matching troubleshooting page |
| Anything a customer will notice | Unreleased changes |
| A feature’s availability | Feature Inventory and Coverage Matrix |
Writing rules
- Document only what the product does today. Mark the rest Planned or Not available. Never describe a feature because competitors have it.
- Explain the business idea in plain words first, then the BillHive steps.
- Use the labels the portal shows, in bold, exactly as spelled on screen.
- Use tables for fields and comparisons, and Mermaid for flows.
- Use rupee amounts and realistic numbers in examples. Show the arithmetic.
- Link to the one page that owns a topic instead of repeating it.
- Don’t include internal service names, database tables or credentials in user pages. The Technical Reference is the only place for architecture.
- Use real screenshots from the portal. Never mock one up.
Release notes
- Add entries to Unreleased changes as features merge.
- When a release is cut, the release owner gives it a version and date. Move the entries into a new
changelog/vX-Y-Z.mdxpage. Never invent a version or a date. - Write for customers: what changed, why it matters, what they need to do. Leave out commit messages.
Review cycle
- Each page carries a Last reviewed date where it was checked against the app.
- Every month, re-check the Feature Inventory against the portal menus and
SUBSCRIPTION_ACTIONS, the rule that decides which subscription actions each status allows. - Run the docs build before merging. It catches broken MDX and broken page links.