Why We Write the Operations Manual Before We Write the Code

If you can't describe how a system will be operated, you're not ready to build it.

This surprises people. We're a software company. Our clients hire us to build systems. And one of the first things we do — before architecture diagrams, before database schemas, before anyone writes a line of code — is draft the operations manual.

Not the user manual. Not the API documentation. The operations manual: the document that describes how the system will be run, day in and day out, by the people responsible for keeping money moving.

It's the most valuable document in the project, and it exists before the project has produced anything to document.

Why before, not after

The conventional approach is: build the system, then document how to operate it. This makes intuitive sense — you can't document something that doesn't exist yet.

But here's what actually happens when you document operations after the fact:

1. The system is built around developer assumptions about how it will be used
2. The operations team discovers that the system doesn't match their workflow
3. Workarounds emerge — manual steps, external spreadsheets, undocumented processes
4. The operations manual (if it's ever written) documents the workarounds alongside the system, creating a patchwork of "do this in the system, then do this outside the system"
5. The next developer inherits a system whose actual operation bears little resemblance to its design

The operations manual written before the code prevents this. It's not documentation — it's a design tool. It forces you to think about day-2 operations before you make day-1 architecture decisions.

What goes in it

The daily rhythm

What does a typical day look like for the person operating this system?

• What's the first thing they check when they sit down?
• What reports do they run?
• What do they review and approve?
• What exceptions do they handle?
• What's the end-of-day process?
• What constitutes "done" for the day?

Writing this out before building the system reveals the workflow the system needs to support. If the operator's first action is checking bank balances across six accounts, the system needs a consolidated balance view. If the end-of-day process is a reconciliation sign-off, the system needs a sign-off workflow.

These requirements don't always appear in a BRD. The BRD describes what the system should do. The operations manual describes how people will use it to do their jobs. The difference matters.

The exception playbook

Normal operations are easy to design for. Exceptions are where systems either support their operators or abandon them.

For every exception scenario, the manual describes:

• How the operator will know there's a problem (alert, dashboard indicator, report flag)
• What information they need to diagnose it (transaction details, bank statement comparison, audit log)
• What actions they can take (retry, override, escalate, reverse)
• Who they escalate to if they can't resolve it
• How the resolution is recorded

Writing this before the code means the system is built with exception handling in mind. The exception queue isn't an afterthought — it's a core feature. The escalation path isn't a sticky note on someone's monitor — it's a workflow in the system.

The handoff points

Where does human judgment intersect with automated processing? These are the handoff points, and they define the system's user experience:

• Automated matching runs → exceptions are queued → operator reviews and resolves
• Payment batch is prepared automatically → operator reviews totals → operator approves → batch is submitted
• Bank statement is ingested and parsed → reconciliation runs → operator signs off on the results

Each handoff point is a design decision: what should the system present to the operator at this moment? What information do they need? What actions should be available? What should be locked down?

If you define these handoff points in the operations manual before writing code, the UI design follows naturally. If you define them after, you end up retrofitting screens to match a workflow that was discovered, not designed.

The failure modes

What happens when things go wrong? Not edge cases — actual failure scenarios that will happen in production:

• Bank API is down for two hours during peak processing
• A bank statement doesn't arrive by the expected time
• The reconciliation shows a large unexplained discrepancy
• An operator makes a payment to the wrong beneficiary
• The system itself goes down during processing

For each failure mode:

• How will the operator know? (monitoring, alerts, manual discovery)
• What is the immediate response? (pause processing, switch to manual, escalate)
• What is the recovery process? (retry, reconcile, reverse)
• How is the incident documented?

Writing this before building means the system has monitoring, alerting, and recovery workflows built in. Not added in sprint 8 after the first production incident.

How it shapes architecture

The operations manual isn't just a document for operators. It directly influences technical decisions.

Example: batch approval workflow. The operations manual says: "The operator reviews the payout batch, checks the total against the available balance, and approves it. If the total exceeds the available balance, they split the batch."

This means the system needs:

• A batch review screen showing itemised payments and totals
• A real-time (or near-real-time) balance check
• The ability to split a batch — not just approve or reject
• An audit record of who approved what

Without the operations manual, a developer might build a simple approve/reject mechanism and discover the split requirement in UAT. With the manual, the split functionality is in the first sprint.

Example: reconciliation sign-off. The manual says: "At end of day, the operations manager reviews the reconciliation results and formally signs off. If there are unresolved exceptions, they must be acknowledged with a reason before sign-off is allowed."

This means the system needs:

• A sign-off workflow with user authentication
• A mandatory acknowledgement for open exceptions
• An audit trail of sign-offs
• A report that can be generated after sign-off showing the day's final reconciled state

None of this is complex. All of it would be missed if you designed the reconciliation module as a technical matching process rather than an operational workflow.

The living document

The operations manual isn't finished when the code starts. It evolves alongside the system. As features are built and tested, the manual is updated to reflect the actual behaviour. As operators start using the system (during UAT, parallel run, or shadow mode), they provide feedback that refines the manual.

By the time the system goes live, the operations manual is accurate, tested, and owned by the operations team. It's their document, not a developer artefact.

And when something changes — a new bank integration, a new merchant type, a new regulatory requirement — the manual is updated first. Then the system is updated to match. Never the other way around.

The resistance

We get pushback on this approach. "You're spending time writing a document instead of building the system." "This feels like waterfall." "Can't we just start coding and figure out the operations later?"

The answer is: yes, you can. And you'll spend twice as long overall.

Every hour spent on the operations manual before coding saves multiple hours of rework, UAT failures, and post-go-live firefighting. Not because the document is magic, but because it forces the questions that need answering before the system is designed: How will this be used? By whom? What happens when it goes wrong? What does "done" look like for the operator, not the developer?

These questions have answers. But the answers come from the operations team, not the codebase. And if you don't ask them before you start building, you'll discover them in production — which is the most expensive place to learn.

Zenlime starts every payment system engagement with the operations manual. Start a conversation.