I’ll be talking about the secret sauce behind successful APIs, so let’s kick off proceedings with some time travel. Imagine you were in 2019: a lot of organisations were satisfied creating reference documentation, and leaving the rest up to the developers expertise when it came to integration, use cases etc. And then came 2020 and the pandemic, we were all scrambling to find ways to communicate with our users about APIs and our ecosystems. In a true sense, 2020 has provided organisations with a fair kick up for realising the value of accelerating and scaling their API offerings. Successful API products have always been around before then, but we’ve missed some vital signs until 2020. What is the secret sauce behind successful APIs and the uptake? Let me start off with a story. This is about an initially unsuccessful API project. A couple of years back, I was working on a large scale API project where we were designing and building some APIs for the energy market in Australia. Our end goal was to have developers and project teams on the user side integrate our APIs into their workflows, just to be able to provide critical energy information to the market. The project kickoff went really well and our end deliverables were clearly communicated to the project teams. We had a whole suite of wholesale and retail APIs and a clear cut product user interface to go with it. Yet, within a few weeks of the kickoff, things went pear shaped. Let me tell you why. There are a number of places where we faltered as a team: we messed up our timelines, we didn’t take into consideration customer input about the product design and use cases. Since this was such a huge project around a market change, obviously there was the predictable hesitancy in its uptake and all manners of pushback from different different users. To me as a tech writer, the main problem was the lack of timely documentation and communication around it. Our users were not happy with the technical documentation provided and they found it confusing. While we were busy designing the APIs and trying to get our users to integrate, they were reluctant because there wasn’t sufficient technical documentation around the APIs. I’m not just talking about API reference information, I’m talking about technical specifications, user guides, integration content. At the end of the day, the project was delayed, and we had to go into some sort of a damage control mode to make sure we didn’t fail to deliver on a new timeline.
If you asked me to summarise the whole project, on a slide, this is what I would have had up as a report card for my management.
It was a great learning experience for everyone even though the project schedule was blown out by three months. To be honest, three months is a decent slippage, considering the nature of market leading projects but it still provides a good insight into focusing on what we could improve. There are always things within a project that sometimes do or don’t work and are out of our control but these are some of the things we could have improved. It is through this experience of working on numerous API projects that I’ve come to understand and truly appreciate the secret sauce behind successful APIs.
Documentation
Often overlooked, often put up on the sidelines as an afterthought, but there is so much value that good documentation provides to successful API projects. When I say documentation, I’m not just talking about API reference information which is probably the core of it. I’m talking about the whole lot that goes beyond technical information: documenting decisions, documenting technical specifications, user guides, integration content, and even support material. Let’s look at the journey of an API. How do you typically visualise it? If you’re an API producer, someone who produces API, these steps or phases will resonate with you even if you will no doubt have some variations of this. The core of the API journey revolves around defining and designing the APIs, which is step one. You’re defining what the API is, what it does, and designing it before you get cracking on with building it. Step 2 is mocking the API. It is a mock representation of a service to pre-test that the API design actually works. That’s pretty common sense, you just make sure the design works before you actually invest. Once the mocking works sufficiently well, you go into the development where you are building the API and putting your money where your belief and your conviction is. Once you’ve done your development, you then go into the testing, you put your API through its paces when it comes to contract integrations, performance, security, everything. And now that you’ve gone through the first four steps, step five is the most crucial one where you are actually bringing the API to life, publishing it out into some format where your consumers can then start using it. And then the last step is managing the API. That’s everything that comes after, like onboarding, authenticating, monitoring, automation, bug fixes, optimization, making it discoverable, and also collaboration. So you’ve done your bit, and you’ve unleashed your APIs to the world. But is this it? Is this all there is to the journey of an API? We’ve covered the steps taken to bring an API to life but how do you think a consumer approaches your API product? What is their thinking when they look at APIs coming into the market rapidly? In this case, let’s assume your consumers are developers but in reality, you know it’s not just developers, your consumers are a lot more varied than that. If your consumers are developers, they typically stumble upon or are directed towards your API products in the discovery phase. They want to know the possibilities and limits of your API, find out what is possible in the least amount of time and with minimal effort. If they do get beyond this step, they onboard and then start integrating your API into their products. Once they have integrated, they interact with you and provide feedback on APIs that they’re using. Maybe they’ve got feature requests, maybe they want something else done within the API, or expand the scope of what the API does. And over this journey, they will appreciate the self-serving nature and support that you’ll provide via various channels.
So what is the point of all this? What am I trying to really say here? In the Smartbear’s state of API survey in 2019, API documentation was one of the top criteria for consumers to evaluate and adopte your APIs. The lack of focus on documentation as a top priority proves really costly for API producers. This survey also points out that in a previous iteration of the same survey in 2016, documentation was not even in the top five, but has quickly rose to prominence in the last three years. It’s got a little bit to do with the pandemic because a lot more people are now relying on sufficient support and documentation to be able to start integrating your APIs. It’s a wide economy, there’s APIs populating pretty much every industry there is so if you don’t have accurate and detailed documentation, your APIs are pretty much redundant the moment you release them.
Problems and solutions
From experience, there are a couple of problem areas that I’ve identified with API projects, working on such projects in the past. The number one problem is that product teams are so taken up with the API design and delivery that they often forget who they’re designing and building the APIs for. How do you go about solving it from a documentation perspective? Before you go down the path of design and testing APIs without any customer needs analysis, document a use case or planning document that allows you to have a shared understanding of customer needs. Make this document a living piece of knowledge and revisit it often to make sure you’re updating your goals. The second problem is that simply having good design does not necessarily translate into marketable APIs. This is not necessarily dissing the value of design, though, if anything, it only adds credence to the fact that design is so vitally critical. If you do not invest time, resources and right skills in documenting your APIs, they’re pretty much useless the moment you release them to the market. How do you get around that then? Document your design decisions, and iterate often to make sure your APIs are actually turning into something usable. The better your design and your APIs are adapted to the customer perceptions, the better your chances are that the customers might actually start integrating with your APIs more successfully. Third problem: Teams work in silos and there’s no communication between them. The business and technical teams hardly communicate with each other, and fail to share a common vision. Things quickly get out of hand, the business is busy promising the sun and the stars to users when the technical team has no knowledge of the scope of what was acquired upfront. Keeping this balance is easier said than done but technical writers can actually help effectively document everything.
Documentation and the value technical writers bring to such API projects
Now that I’ve let you in into the secret sauce, let’s look at these ingredients. The list is not exhaustive, there might be some more content that is repetitive but allow me to walk you through the wonderful world of technical documentation. Assuming you’ve roughly followed the API lifecycle journey, let’s see how you can actually convert this into use documentation around these different steps.
Step one (design) is a good place to start documenting your API but it is actually even better if you start documenting the design before you write a single piece of code. Along with documenting the design, this is also a great opportunity to document your terminology, setting some baseline metrics for content and also capturing key requirements.
Step two is mocking. While developers and testers are creating simulations with mock servers, you can get started on creating tutorial style information. Increasingly, these days APIs need to be made available to consumers before they can try them out and commit to using them. Using this data, you can create useful content that allows consumers to trust your APIs processes and see results instantly. Having the sort of tutorials and other visual content that validates the test is an excellent way of increasing trust.
Next step is the core of all this API development, the process of creating a programming interface that forms the base of all AP applications dealing with data, or needing to communicate between two products, or two services or two systems. So going back to my story, I distinctly remember this step in the process, where I did a bulk of my documentation as a tech writer. One of the key deliverables of the project was a technical specification that allowed users to understand the structure of the API, the various endpoints and requests and responses, and so on, and so forth. This is the ideal step to start documenting user stories because we’re not only just creating APIs for a single user, there are multiple users who will be using and at least getting to know your APIs for their particular use cases. You can create user flows, task use cases, and work on documenting as many things about the APIs as you can to save you tonnes of pain later, when you actually market and publish your APIs.
Step four is testing the API directly for their functionality, viewpoint reliability, performance and security. Testers make excellent collaborators on planning onboarding experiences for API consumers as they are the closest to the API functionality with respect to integration. Documentation is one of those really critical skills that operates on every level. Working alongside testing teams, you can be actively engaged in improving error messages, validating responses, success messages, also planning on creating user guides and adding material for the APIs themselves. If you’re confident that your API definition is ready for production use, that means you are good to publish it.
Publishing is a way of showing that the API is in a stable state, and its endpoints can be reliably called from other applications. This is literally the point where it all becomes a reality. Ideally, if you followed along on the documentation journey, you are ready for the docs to be unleashed as well. Your Docs team would have a number of deliverables ready, like reference documentation, use cases, examples, user guides, tutorials, visual content. You could also have operational content that helps you support troubleshooting, bug fixing, feature requests or anything in terms of managing future state of the APIs. Do you know what your consumers are looking for in your API documentation? The Smartbear API report had some indications of this, the top five most important things are like your examples, status and errors, authentication, error messages, like for a “getting started” guide. There’s a whole list of documentation effort required to bring all of this into fruition.
Post publishing, it’s now time to manage your API assets: the API themselves, but also the content to gain deeper visibility into your APIs performance, your usage and evolving requirements. This is where your consumers are providing you more feedback. This is an ideal way to evaluate users feedback on documentation and fine tune the content to meet the user needs. Support content is a big piece of this process, it adds things like troubleshooting, use case information for different scenarios. These are the different sorts of ways you can actually help your management or support teams create useful content for your consumers.
Adding some sizzle
It’s not the end of the journey. Having worked on multiple projects involving APIs, I’ve seen and felt how consumers provide feedback closely. Publishing API reference information may be well and good but how do you go about adding some sizzle to this dish? Full disclosure, I currently work for an organisation that is in the business of delivering awesome developer experiences via their products, or more specifically, the developer portal. Developer portals are how your consumers understand, interact, adopt, monitor and govern your API products. Unlike user interfaces, or web pages for other products, APIs really can’t claim to be intuitive as they literally have no front end. In some cases, they might, but the bulk of it is just a piece of code. They’re just merely endpoints that return results and status code. Developer portals now have a slightly broader function than just being pure reference content; what they do essentially serve as a Self Support Hub for anything to do with the organization’s API offerings. They’re essentially the face of your APIs coming out of the organisation, they’re your brand value in this digital age. And, and this point is where you realise that they just don’t serve developers, they become the go-to place for education, training, community and marketing. Here are a couple of scenarios on how to shape your developer portals into becoming these self-sustaining hubs for your API offerings. When you look at education, typically with a full developer portal, you will have topics covering not only API reference material, but also content around how to onboard new users or developers, getting started, technical details of authorising and authenticating and some solid use cases. When you have a full set of documentation that explains the basic behaviour of your APIs, it is worth its weight in gold. It educates your consumers and also the business stakeholders on how to successfully integrate with your APIs. In addition to educating, developer portals also function as an excellent training ground for developers and other users to use the API product. This is where technical writers get to shine by adding in a good overview, information, scenarios and examples of API endpoints and where they can be used. They can also depict various workflows and user journeys of what’s possible with your APIs. Using good technical writing practices, writers can actually add the context around the APIs themselves. Developer portals are also excellent ways of interacting with your community. If your APIs are public and open source, you could have a community factor to your development portals. You factor in things like open source contributions, feedback from users directly, something that can be quickly actioned and expanded within your API products or API offerings. As far as brand and marketing are concerned, if your core product is any API, or APIs are part of your software strategy, developer portals can be part of it too. They’re an excellent way of selling your product and generating a level of trust from your users with pricing models, evaluation methods, and showcasing other customer implementations.
Quick summary
The difference between successful and unsuccessful projects is often how much you’ve documented throughout the process. Documentation is an extremely powerful tool to bring along everyone on the same journey. The lack of focus on documentation as a top priority can prove costly for API providers, and that’s very documented in the state of API service. The key to successful APIs is how well your customers can discover, onboard and integrate your APIs into their products. If you have good documentation to showcase and educate customers, you can be well assured of their success.
Q&A Section
Q: What do you see as a challenge in API documentation compared to documenting other software products that have user interfaces or digital products?
A: From experience, I think it comes down to the fact of having that early access to the development methods and the designs. Typically, with software products that have a user interface, the technical writers get to play around with the particular products in some sort of a safe environment. With APIs, it’s a little bit different because there is no UI, it comes down to the fact that if you’ve got good design practices, and if you can visualise it properly, it then adds more value.You need to make sure you’ve got access to the right products in the right resources and that the knowledge is documented. It makes API documentation a whole different challenge.
Q: How do you make your API documentation appealing for non technical business, or executives who are willing to make investment in their decisions?
A: It is tricky because organisations are often in the mindset of looking at API documentation as just reference materials. However, if you invest in the right resources, like technical writers, or other professionals out there, like UX design, or UX writers, or content designers, or even people with a technical marketing background, who can actually help you craft that message really well, it adds value in terms of marketing. It also means you have enough material to make the APIs appealing. Investing in the right resources can make a world of difference in the long term and save money.
