Modern APIs are quickly changing the software development industry.
Thanks to these extraordinary pieces of code, software developers now have a much easier job creating amazing products and getting them to market faster than ever.
In this article, you will find out what API documentation is and how they’re creating a whole new world of opportunities for technical writers with an unquenchable curiosity for cutting-edge technology.
There’s much to learn, so let’s get right into it.
What Is an API
In plain English, an application programming interface (API) is a piece of code that allows two software products to communicate with each other.
Whenever you use an app or a SaaS product to retrieve a piece of information, an API is how that information is requested and delivered to you.
Still a little unclear?
Let’s explain with an example.
Say you wanted to book a flight for your long-overdue vacation. You’d probably use an online flight finder, such as Skyscanner.
You’d put in your origin and destination points, dates, and other information relevant to your trip.
Your travel app would then connect with an airline’s API, which would request possible flight options from the airline’s database.
Once some options that fit your parameters are found, the API would deliver them back to your travel app for your selection.
Do you see the value in that?
Without an API, you would need to access the airline’s database and manually look for flights that meet your criteria, wasting a lot of time and maybe even quitting the service altogether.
That’s the beauty of APIs. They save users a lot of valuable time and do all of the heavy lifting when it comes to searching for and delivering information from all kinds of online databases.
But it’s not just ordinary internet users who benefit from APIs. In recent times, developers and software companies have started using APIs to get their products to market much faster than ever before.
For example, consider an app like Uber. One of the most useful features of the app is the interactive map that guides drivers to customers and shows customers how far their driver is.
But building such a map from scratch would be an enormous challenge and would probably cost the company more than the app itself.
Luckily, Google Maps offers an API service, which allows the Uber app to simply access Google Maps to connect drivers and customers.
Long story short, software service providers can now offer APIs to other developers, meaning developers can use APIs instead of building features (like Uber’s map) from scratch, once again saving loads of time and money.
As a consequence, APIs are now designed, packaged, and sold much like software products. For instance, have a look at Spotify’s API below.
At first glance, it looks much like the original Spotify app, doesn’t it? That’s because this is a product meant for consumption.
But where the original app is intended for music lovers, this product caters to developers.
And as with any other software product, APIs need quality technical documentation that will guide developers through the features of the API and help them integrate it into the product they are building.
That’s where API technical writers come in.
We recommend you to read our article about - How to Write API Documentation: The Ultimate Guide - before you dig deeper in this article.
What Does an API Technical Writer Do
When APIs are commercialized in the way we described above, they become products made by developers for developers.
However, that doesn’t mean that the developer that gains access to an API will automatically know how to work with it.
That’s why APIs come with extensive technical documentation so that developers can understand and learn how to implement the API they are working with.
Let’s look at our example from Google again.
Notice something peculiar?
As soon as you access the Google Maps APIs, you have the option to start exploring their documentation.
All of this documentation was written by Google’s API technical writers. So what do these unsung heroes of API technology do?
In a nutshell, their job is to thoroughly explain the features and use cases of the API and guide new users through the process of implementing and using the API for their benefit.
The first part of their job is quite similar to what a marketer does, and that’s providing an overview of the API.
This is important work because both potential users and developers just starting to use the API need to know exactly what kinds of problems the API can solve and the benefits of integrating it into their own software.
Back to our Google Maps example. Here’s an overview of Google’s Map API for JavaScript.
As you can see, this API overview does a perfect job explaining what the API does and who it’s intended for.
Even more importantly, API technical writers are tasked with teaching developers how to successfully integrate the API and use its functions correctly.
This means writing tutorials and step-by-step guides for the API, like in our example below.
It’s easy to see why this is such an important role. Ultimately, it doesn’t matter how amazing or helpful the API is if users can’t figure out how to implement and use it to improve their software.
Long story short, API technical writers form the link between the engineers who develop APIs and the users (also engineers) who implement them into their own products.
They inform the users of all the things they can do with the API and help them achieve their goals by providing guidance on how the API is used.
Who Can Write API Documentation
Technical writers need a specific set of skills, no matter what kind of technology they’re writing about.
Not only do they have to be excellent storytellers who can easily explain complex concepts, but they also need to have a working knowledge of the technology itself (for example, knowledge of programming languages if they work in development.)
However, writing API technical documentation can be even trickier.
Remember, the primary audience for API documentation are developers, not end-users with very little technical knowledge.
That means that API technical writers need to be even more skilled in development processes and have more technical knowledge than is usually expected from technical writers.
Have a look at this job ad on LinkedIn as a good example of the many hats an API technical writer needs to wear to do quality work:
As you can see, programming experience is a must, and so is extensive knowledge of software development protocols and platforms.
Clearly, if you want to address developers, you need to talk the talk and walk the walk.
So let’s look at some usual candidates for the position of API technical writer to see how they compare.
Developers
Considering the job ad we examined above, you’d think developers are perfectly positioned to write API documentation.
After all, who better to guide new users through complex code than the good people who wrote it in the first place?
One slight problem, though.
Truth be told, developers are notoriously bad writers. But that isn’t necessarily their fault.
Explaining their work to others usually isn’t a developer's top priority, nor their preferred type of work, so burdening them with documentation might not be a wise idea.
However, this doesn’t mean developers don’t have any documentation duties.
They should still document their own process with comments and notes (like in the example above) as these are invaluable to, among others, writers who create the API documentation.
Technical Writers
As we said, writing API documentation can be quite a challenge for even the most experienced technical writers out there.
Nevertheless, API documentation writers do usually come from a technical writer background. After all, writing clear, consistent, and engaging documentation takes a lot of talent.
The other necessary qualifications, such as basic coding skills, can be learned along the way.
At least that’s what the experts are saying:
Technical writers are a good choice for writing API documentation, especially if they can work closely with developers to fill in the knowledge gaps caused by a lack of programming experience.
Developer - Writers
This subset of writers constitutes the holy grail of API technical documentation.
These individuals fall into one of two categories: they’re either ex-writers who decided to learn to code and become developers themselves, or ex-developers who find more enjoyment in writing.
Writers who come from either of these categories will be able to produce clear and helpful documentation and have no problem understanding the ins and outs of the API.
They’re the best choice for the role of API technical writer.
So what’s the problem?
Well, they’re extremely rare. And if you think about it, that makes sense.
Coding and writing are different skillsets that usually attract different personalities so it’s rather difficult to find an individual who is gifted at both.
In conclusion, the best API technical writers need to be knowledgeable about programming, as well as skillful at writing.
This is a difficult mix to find, but that doesn’t mean API documentation should be left to the developers themselves.
A much better approach is to work with capable technical writers and invest in their coding and other development-related skills.
Benefits of Writing API Documentation for Developers
Before you start this part of the article, you might wanna check our blog post about how to write good developer documentation to have a better image about benefits of writing api documentation for developers.
To sum up some of our previous points, API technical documentation is not easy to create, and finding quality API technical writers can be extremely challenging.
So the question needs to be asked: is creating API documentation even worth the trouble?
Well, if you’re asking the developers tasked with integrating the API, the answer is a resounding “yes.”
First of all, it’s important to understand that the API market has been skyrocketing for some time now.
Companies seem to be very aware of the value these products can bring to their business and as a consequence, there’s now an API for virtually any feature a developer might need.
In fact, in 2018, the total number of APIs available on the market has passed 22,000.
With such a wealth of choices, developers need quality documentation that will adequately explain what problems they can solve with a specific API and how it can improve the product they’re working on.
In that sense, API technical documentation plays an important role in the selection process and helps developers choose APIs that fit their needs perfectly.
Secondly, API documentation can significantly improve the developer’s user experience.
It guides them through all of the steps they need to take to successfully integrate it with their own software, meaning it’s especially important for the developer onboarding process.
As with any other kind of technical documentation, API documentation shows users how to work with the product and helps them achieve success faster, with fewer obstacles on the way.
Finally, quality documentation can help developers build their products to go beyond what they initially thought was possible with the API.
Let’s visit Google Maps’ APIs one last time.
Imagine you’re developing an app with a simple map function.
You access the appropriate API, but along the way, and thanks to the technical documentation available, you discover a whole world of possibilities.
Since you’re already building a map feature, why not style it to make it look on-brand? Why not add geocoding capabilities or travel distance matrices?
Thanks to the hard-working technical writers of Google, all of these possibilities are now within your reach.
These benefits are just some of the great things API technical writers bring to the table with their documentation, but they should be enough to convince anyone that API documentation is a crucial component of the rising API economy.
Tips for API Writers for Creating Better Documentation
Throughout this article, we’ve tried to make one thing clear: top API technical writers possess a unique mix of technical knowledge and writing skills.
Read recommendation: 6 Tips for Writing Great API Documentation
Therefore, if you’re confident in your writing ability, it would definitely be in your interest to spend some time learning about code and software development.
If you’re still new to coding, there are many excellent resources that will give you a solid starting point and teach you the basics of computer programming, such as Codecademy.
According to the experts, you don’t need to become proficient in multiple languages to do well as an API writer, but you will have to be able to hold your ground. Here’s some first-hand advice from a senior technical writer:
Another great tip we can discern from the advice above is to know where to look for answers if you ever get stuck.
So if you haven’t already, take some time to create accounts on Stack Overflow and any other communities that will help you in your work.
In this line of work, a writer is only as good as the tools they use.
For technical writers, that means doing their best work in quality documentation software, so our next tip is to find the documentation software that best suits your needs.
We made a top about tools for documenting your APIs you should check out!
Our own product, Archbee, offers stronger API support than other software products in this category.
With Archbee, technical writers can easily import API reference information through OpenAPI files, or they can insert single API endpoints and provide as many details about it as they need.
In addition to that, Archbee has a powerful editor which writers can use to create more than twenty custom blocks for their documentation, and that includes a code editor for different languages.
Last, but not least, always remember that you’re writing for engineers.
Their time is incredibly expensive, so focus on providing clear, concise, and easily digestible information, and do everything you can to keep your readers from wandering around the API documentation you’re responsible for.
That means making your documentation easy to navigate, accessible, and searchable.
Luckily, quality documentation can help here, too.
Archbee has powerful search capabilities, drag and drop menus, and even knowledge graphs that present information in visual terms, making it easier than ever for users to read their way across the entire workspace.
To sum up, if you want to become a top writer in the exciting world of APIs, don’t neglect the technical side of your job and use the resources and tools created for technical writers to your advantage.
Conclusion
As the API economy continues to grow at break-neck speeds, new opportunities are presenting themselves for everyone in the app and software development community, and that includes technical writers.
API technical writers need to have an almost unique mixture of technical and creative skills to rise up to the challenge of writing documentation intended for developers.
If you’re considering a career in this exciting field, we hope this article has given you a good idea of what APIs are, what it takes to write documentation to support them and what does it mean to be an API technical writer.
