In an ideal world, a developer visits your documentation site, skims easily through the navigation, lands on the right content, finds perfect code samples and gets started right away.
That’s in an ideal world…
In the real world though, the truth is far from it. While there are some great API documentation sites out there, bringing the best on the table has been a challenge even for the big players.
In a developer survey conducted in the past, Facebook, Google and Twitter ranked top in the worst API experience and the key reason behind it was noted to be “poor documentation”.
Surprising as it may sound, out of the other common issues faced by developers such as frequently changing APIs, poor error handling, etc., bad documentation was brought up as the most serious pain point. Issues such as lack of example code, incorrect or incomplete API data structures and functionality were one of the many developer headaches the survey reported.
So, what exactly does it take to create a top notch developer documentation?
The tech writing team here at Razorpay, took up the task to ascertain what an “ideal” documentation means and what it takes to build one. Thus, we set out to create a perfect piece of literature for developers that would not only be useful but also something they absolutely love going through!
In this quest, began our journey to Citadel – a place where knowledge resides.
Citadel is our in-house documentation platform built by developers for developers. We started with the aim to create a robust, developer-friendly site that would be the favourite go-to place for our merchants and technical audiences alike.
To achieve this, we needed to build our own unique platform from scratch since the current documentation tools in the market had their limitations. More importantly, considering the variety of products and features that we offer which are interoperable, we needed a platform that would take care of both width and depth of technical documentation at the same time.
Throughout this journey, the team put themselves in the developer’s shoes: posing problems as a developer and resolving them like one. This project started mid last year and we are now at a point where our beta site is live with all the nuances (frontend and design included).
Instead of executing in one-go, we staged bits and pieces of new documentations on the platform throughout the period. When shared with visiting developers, we got a chance to personally interact and incorporate suggestions or iron out flaws. This iterative process is what has helped us develop Citadel into something developers love interacting with today.
Following are what we think serve as the cornerstones of a documentation site and in retrospect, also the reasons why it is always better to build your own custom documentation platform:
Empathy – because developers deserve better!
Developers are hugely mistaken beings. While they can create magic with code, they can also end up in a miserable whirlpool if the documentation is convoluted with no real structure to get around.
You could even be pushing them into “Developer Distress” – a black hole of sorts, from where returning seems impossible without some mud-slinging, hair-pulling, and tempers running high. Sounds like a pretty grim place to be, right?
Thus, empathy – because your developers deserve better! Asking questions like ‘what’s the most annoying thing to come across in a documentation site?’ or ‘what would confuse a developer’ holds answers that are probably your cues to what you DO NOT want to do.
Becoming a person of empathy helped us take the following calls for Citadel:
- Dividing the integration content into bite-sized chunks that a reader can easily understand and implement
- Providing tailored content based on language selection
- Using a three-column layout for showing codes
- Using ready-to-use code samples
- Using syntax highlighters for better readability
A solution that looks at problems empathically is usually a solution that works.
UI, UI and UI
The UI is the face of your documentation. You’ve got to be spending enough time on designing and creating the UI because nothing makes the best first impression than a pretty face. UI experience can have extreme outcomes of either putting off your readers or inviting them to read more.
Your choice of colours, fonts, and aesthetics go a long way in adding value to readability. What we kept core, was Razorpay’s official design theme and minimized on the frills. In fact when it came to the UI, keeping it simple was the mantra we liked best. Some of our UI/UX aspirations have been:
- Adding clear demarcation of sections using lines and a generous amount of whitescape
- Adding responsive top navigation for selecting different languages
- Adding horizontal scrollbar in stretched out code boxes
- Making the left Nav bar collapsible for condensed view of menu items
- Using different font styles for different API parameters
Focusing on the UI/UX is the key to engaging your readers productively, rather than taking them in circles. Here’s a little sneak peek into Citadel as we are building it that includes some of the the changes mentioned above:
Foresight for long term solution
You don’t have to be a superhero to have foresight (you might need a bit of imagination though!). Foresight is as simple as knowing the next obvious course of action and being one step ahead in solving a problem even before it is detected. We tried to preempt and plan in advance while building Citadel in the following ways:
- Providing a button to copy code samples
- Indexing all the topics alphabetically or category-wise on the home page
- Using breadcrumbs on top of pages
- Using Previous and Next button in the footer to direct readers logically
While putting yourself in the shoes of the developer is crucial, sometimes you just need to outdo their expectations to make that extra bit of a difference.
As we inch closer towards going live with Citadel, it is overwhelming to see our vision come to life. We can now safely say that building your own documentation is definitely worth giving a shot!
Watch out this space for updates on Citadel and do give us your honest feedback!
Coming soon!
