Skip to main content

Contributing

CBA Operations is a living source — the bank uses it; we maintain it; the regulator audits against it. Every change you make ships to docs.korastratum.com/cba/operations/... and to the per-persona PDF bundles on the next release.

Before you write​

Decide which one of the four doc types you're producing. Conflating them produces 60-page PDFs that are hard to scan when something is on fire — that is exactly what we are trying to avoid.

  • Reference — describes a screen, field, table, or report. Stays accurate forever; updates only when the UI changes.
  • Walkthrough — sequential procedure ("how do I…"). Should number its steps; should have a "What success looks like" closing section.
  • Runbook — short, action-first, no preamble. The reader is under time pressure. Lead with "If this is on fire, do X immediately"; explain rationale at the bottom.
  • Decision — branching tree. The reader is asking "which path applies?" Render as a flowchart or numbered conditions, not as prose.

Author the page in the matching directory: procedures/, reference/, runbooks/, decisions/. Personas index pages live in personas/.

File checklist​

  • Frontmatter present and valid (schema).
  • personas: list is accurate — every role tagged actually uses this procedure.
  • cbn_clauses: cited verbatim against the CBN clause registry if applicable.
  • last_verified: is today's date (you literally just confirmed it works).
  • No <Tabs> / <TabItem> / other React components — operator content must be plain Markdown so the Pandoc PDF build succeeds.
  • Screen names and field names match the live console exactly. If the console says "Lodgement", don't write "Cash Deposit" — match the UI; the user is reading the docs while looking at the screen.
  • Currency amounts use the ₦ symbol and thousand separators (₦1,250,000.00, not 1250000 NGN).
  • Every "click X" instruction names the actual button label as it appears on screen.
  • Every link to another guide is relative (/cba/operations/procedures/vault-to-till), not absolute.

Voice & style​

  • Address the reader directly — "You select the customer", not "The user is to select the customer".
  • One step per numbered item. If a step has sub-steps, indent them; do not pack multiple actions into one number.
  • Surface decisions early. If step 3 depends on whether the customer is corporate or individual, the choice belongs at step 3, not in a footnote.
  • Show the screen. Use the <Screenshot> shortcode for canonical screen captures — keeps screens consistent across guides.

Screenshots (coming in Tier 2)​

Phase 1 ships without inline screenshots — we don't yet have the build tooling to keep screenshot freshness honest (the UI moves, screenshots rot, the doc lies). Phase 2 layers in a <Screenshot> component with a last_verified parameter that surfaces staleness automatically. For now, describe the screen in words; refer to fields by their on-screen label.

After you push​

  1. Open a PR against main in badedokun/kora-docs.
  2. CI runs the operations lint (frontmatter schema + no-React-components + CBN registry).
  3. After merge, GitHub Pages publishes the web side within ~2 minutes.
  4. The Pandoc PDF build runs on main; tagged release publishes the persona bundles to GitHub Releases.

If you broke the build, CI tells you which lint rule failed; fix the frontmatter and push again.