BLOG
backWhen was the last time you read the manual that came with a new device or appliance?
If you're anything like me, the answer is probably "a long time ago". My approach is to set up the device, push a few buttons and hope for the best. But developers integrating APIs don't have that kind of luxury. Every line of code they write has to work because errors could delay shipping, which could delay timelines or result in faulty products. This is why developer documentation is important.
For the uninitiated, developer documentation is the set of guides and resources that help developers integrate a product into their own systems. Take, for example, a developer for an e-commerce website trying to integrate a payment API from Monnify, Moniepoint’s payment gateway, into their environment. Good developer documentation would help them understand not only the technical aspects of the integration but also the product's business context.
A little while ago, I stumbled across a series of tweets commending Monnify for its stellar developer documentation. I sat down with Muhammad, Developer Relations and Integration Lead at Monnify, to get the lowdown on documentation built for devs, by devs.
The way we see it
We see developer documentation as both a manual and a support channel. Our goal is to make it so complete that developers do not need to reach out to us unless they are ready to go live. That sentence captures our entire philosophy: documentation succeeds when it eliminates the need for itself.
To achieve this, we start by anticipating the questions a developer will ask: What does this parameter do? What happens if I skip this step? What does this error mean? and answering them before the developer even knows to ask. It means writing for the developer who is frustrated, under a deadline, and integrating our product for the first time.
Integrate first. Write second.
The most distinctive thing about our documentation process is where it starts.
Before a single word of documentation is written, we act as developers ourselves and try to integrate the feature from scratch to get it working. Any questions, friction points, or moments of confusion that surface during that process become the skeleton of the documentation.
The structure that emerges from this approach is consistent across our docs: a product overview that explains what the feature does and why a developer would use it, followed by a step-by-step integration guide. Each method gets its own explanation, a small illustrative example, guidance on what to do next, and a working code sample.
Take the sub-account feature as an example. Rather than simply listing endpoints, our documentation walks through the entire lifecycle: how to create a sub-account, what the response looks like, how to handle subsequent actions, and the code a developer can copy, modify with their own credentials, and run immediately. The goal is that a developer should be able to reach a working state without ever leaving the page.
From feature brief to live documentation: the pipeline
We’ve built a structured pipeline to ensure that every documentation we produce meets the same standards.
Step 1: Gather the requirements
Documentation begins with a conversation with the product manager. The goal is to understand two things: what the feature does technically, and what it is designed to help the merchant or customer accomplish. Both matter. The technical detail shapes the how; the business context shapes the why.
Step 2: Create a skeleton draft from product documentation
The product team's internal documentation, feature specs, implementation notes, and product briefs serve as the raw material for a developer-focused skeleton draft, assembled by a Developer Advocate or an Integration Support Engineer. This draft takes product language and restructures it around the integration journey a developer will actually take, using language developers are familiar with.
Step 3: Review for authenticity
The skeleton goes back to the product team for a factual review to verify that the documented behaviour matches the actual feature. This step helps us catch any errors early, while the stakes are low.
Step 4: Simulation and integration testing
This is where the documentation earns its credibility. We simulate the integration using the draft as our only guide, following it step by step, executing the code samples, and observing the responses. Any discrepancy between what the documentation says should happen and what actually happens gets flagged and resolved with the product and engineering teams before we move forward.
Step 5: Engineering review and publication
Once the document is technically sound and tested, it moves into the engineering review pipeline. An engineer converts the draft into code and opens a pull request. The review at this stage checks that we adhered to best practices: consistent formatting using Markdown, no exposed secrets or security vulnerabilities, and the use of stable, current versions of the languages and frameworks referenced in the code samples. Only after that review does the documentation go live.
Engineering review as a quality gate
The engineering review deserves its own examination, because it’s where we treat documentation with the same rigour as production code.
We use Markdown as the standard for all our documentation. This is not just a stylistic preference. Markdown creates a consistent, version-controllable format that integrates naturally into a code review workflow. The pull request is reviewed the same way an engineer would review a software change: for structure, security and correctness.
We take security seriously at this stage. Code examples in documentation can inadvertently model bad practices, such as logging tokens, hardcoding credentials, and using deprecated methods. Our engineering review catches these. Similarly, code samples that reference outdated library versions can silently break months after publication when developers use them. The review ensures our examples are anchored to the latest stable releases.
The result is that documentation on our developer portal is not just written; it is also maintained. It is reviewed, tested, and updated with the same standards as the codebase it describes.
Designing for every kind of developer
We understand that not all developers looking to integrate a Monnify API will visit our documentation site with the same context. Some might be engineers who want to read the API reference, copy a code sample, and be done in an afternoon. Others might need to walk through the architecture before they can begin. It's important to us that documentation serves both.
We handle this by layering our documentation. The step-by-step guides are comprehensive enough for developers who are newer to payment integrations. The code examples are complete and copy-paste ready for developers who just need a working scaffold. The API reference is detailed enough for developers who want to understand edge cases and optional parameters.
Where the documentation ends, our integration support team begins. Because we serve developers across multiple time zones, we operate in shifts to ensure developer queries are answered continuously.
What we’ve learned
After building and iterating on our documentation process, a few principles have proven themselves worth holding on to:
Integrate before you document. The fastest path to accurate, empathetic documentation is to experience the integration yourself. The friction you feel is the friction your developers will feel.
Build a review loop with the product team. Documentation written without product verification is documentation waiting to be wrong. Bake the authenticity review into the process before testing, not after.
Test your documentation like you test your code. Simulating the integration using your own documentation is the most reliable way to catch gaps. If your docs can take you from zero to working, they can do the same for your developers.
Treat the engineering review as non-negotiable. Documentation that ships with security gaps or deprecated code examples actively harms the developers it is supposed to help.
Design for the developer at their worst moment. Our documentation will be read by developers who are stuck, frustrated, and under pressure. We write for that person.
The process we have described here is not a one-time effort. Each new feature, each new integration pathway, each edge case that surfaces in a support request is an opportunity to make the documentation more complete. That is the work: drafts, reviews, simulations, and late-night approvals, repeated until a developer can get from zero to live without us.
Good developer documentation is infrastructure. And like any infrastructure worth having, it is built deliberately, maintained rigorously, and tested before it is trusted.
If you're obsessed with building people-focused solutions, there just might be space for you on the Dream Team. Visit our careers page to see our open roles.
