The tug of war between API Documentation and Developer Guides


API documentation is good when it comes to understanding and using APIs. But nothing beats Developer Guide for aiding to follow feature workflows.

On our online coffee time, we were having chitchats and somehow the discussions about API documentation ended up being the hot topic, considering we are to release Platform of Trust Architecture V2 at the beginning of January 2020. Many have the notions, that for developers, it is enough that you present a comprehensive API Documentation listing all endpoints, usage parameters, try-outs facilities with code examples in a few frameworks. However, few concerns get raised to see how good we are aiding the developers to "make or break" the decision of committing themselves to the service offered.

Can developers understand the workflow and benefits any service is willing to provide?


Burning question!

Being a student of User Experience major in Master's studies, this really woke me up, to say the least. We often seem to think that we were providing adequate resources in a way that it requires the least amount of internal support request. What we could do in a different way to ease the pain of developers? How developers can easily comprehend what a service does without digging through technical complexities.

So what is the problem?

Digging more deeply into the matter, I could draw up the following challenges:

"How to make onboarding simpler, faster, and easier for new developers?" And,

"How to make available resources more developer-friendly?"

Don't get me wrong. I am all about championing good API documentation that can be referred to explore features of any service. API documentation from GitHub, Twillo, and Stripe are my all-time favorites. My argument is that do many API documentations have sufficient structure ensuring developers are not lost into translation with the continuously growing list and endpoints? Are they able to focus on the problem they are trying to solve with the supposed system? On our (definitely good!) intentions to put them in pedestals for their knowledge and experience, we often forget that "Developers are humans too!". Just like consumers of different services, developers will be coming to your services with the aim to solve a problem by trying it out. Remember, a lot of them are also nightbirds, doing their own experiments after a long day's work, trying to come out from the exhaustion with coffee, pizza, and cola. Not to mention the newbie members of the community, who are happy with simple, quick-starters guidance. So in which direction you want to push them? Well maintained but complex API documentation? Or towards a workflow aiding them to onboard and try the service on the flow in lesser time?

“Often by relying only on API documentation (no matter how well it is structured, referenced, or interactive), we are simply loving a solution, NOT THE PROBLEM ITSELF.”
Nazia Hasan
 – Product Manager, Platform of Trust

Let's GUIDE the developers!

We try to solve the dilemma of making harmonized data without the complexities of different system integration. There are multiple core APIs dedicated to this purpose. But when it comes to from registering to generating harmonized data flow in the platform, you need a Workflow. And here a Developer Guide makes all the differences - produce a simple workflow with simple instructions and bare minimal calls to different APIs. The intention is to state the problem, give step by step solutions to solve it and keep the focus ahead. Using guides, you can use the storytelling approach to define a problem, state what implications it brings and how we can tackle the problem with the proposed solution(s).

I'll draw examples from resources in Platform of Trust. We have a core API named Identity, which can be used to represent real-life entities and their interrelationship (e.g. how humidity sensors, rooms, floors, and buildings are interrelated in build environment terminologies) in digital format. There is an API profile describing its capabilities, sample calls, related resources, and API documentation listing all its endpoints, supported methods with needed parameters, and code examples in 4 different languages (cURL, JavaScript, Python, and Java) in a three-column view. Sounds sufficient? Maybe. But what about creating an entire identity network from scratch? One identity network can vary from others in the core elements and their relationship - hence comes the difference in their contexts. Where you can refer to for the contexts? How about where you need to login and get API keys to try the API calls? Are identities associated with some other feature in the Platform and what are the ways to interact? General API documentation often will not contain such details and use-cases. To resolve this dilemma, we offer a guide called Identities and Links. The guide demonstrates, with simple steps and (needed and copiable) API calls, to create and manipulate a demo identity network along with suggestions and referrals to other resources (e.g. contexts for identities, guides to try out advanced features, etc.) relevant to identities. The workflow aims to make it easier for new onboarding developers to understand the concept and try more advanced features of the Identity API.

Now, where does the identity network fit in the entire value chain of generating harmonized data flow? Identity network, apart from data products, apps, and ontology, is one piece of the puzzle for integrating data sources. So we wrote down a quick onboarding guide, Integrate Data Source in 60 Minutes, to demonstrate how individual features of Platform of Trust fit together to implement the entire value chain. The onboarding guide is also comprised of simple step-by-step instructions, aiding people starting from registering to the Sandbox, and ending up with generating harmonized data flow. The steps again consist of necessary API calls, recommended guides for further reading, and resources to carry out harmonized data flow creation. The intention is to start using Platform of Trust features as fast as possible without drowning in technical jargon and complexities.

Let there be Balance!

I may not represent all the developer segments with my own justification. And its no doubt that more talented developers exist out there who can figure out a service overnight. But migrating from a UI designing role towards ensuring flow state Developer Experience, my learning curve aided me to realize how important it is to have simple onboarding for users like me who are somewhat in the middle ground of technical details and business requirements. Or even newbie developers, who are often afraid to break things while experimenting. The necessities of well-structured API documentation with copiable codes, reference models, interaction possibilities will never end or become less important. However, well-produced Developer Guides simply act as the compliment to use APIs to get out the holistic view on what you are getting as a service. And the choice of medium is a lot, text, video, webinar - whichever is convenient!

We are eager to receive feedback even if they are criticisms. It helps us to chart clearer and simpler usage of the service for the developers.

So which side are you in? Continuing the tug of war? Or allowing enough stretch to ensure flow state developer experience?

Check out our developer guides here:


Hi, I'm Nazia Hasan

I am working as a Product Manager in Platform of Trust and I focus on Developer Experience and API Designing. Very soon we'll be migrating to our Developer Portal version 2.0 that would grant customers better experiences in interacting and trying out Platform APIs in Sandbox and access to all resources we provide for a smooth and fast onboarding. Being a person coming from User Experience field, I'll talk about measures we take in Platform of Trust to maintain satisfying developer experience in "human-friendly" blogposts.

Feel free to reach me via, Phone: +358465760561, Email:, Twitter: @NazarahTheCat or LinkedIn: