Documentation HubMaintaining the Docs

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 changedUpdate
A screen, field, button or validationThe 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 eventAPI Reference (generated), Pricing v2 API or Webhook
Something users will ask aboutFAQ or the matching troubleshooting page
Anything a customer will noticeUnreleased changes
A feature’s availabilityFeature Inventory and Coverage Matrix

Writing rules

  1. Document only what the product does today. Mark the rest Planned or Not available. Never describe a feature because competitors have it.
  2. Explain the business idea in plain words first, then the BillHive steps.
  3. Use the labels the portal shows, in bold, exactly as spelled on screen.
  4. Use tables for fields and comparisons, and Mermaid for flows.
  5. Use rupee amounts and realistic numbers in examples. Show the arithmetic.
  6. Link to the one page that owns a topic instead of repeating it.
  7. Don’t include internal service names, database tables or credentials in user pages. The Technical Reference is the only place for architecture.
  8. 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.mdx page. 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.