5 Questions Technical Writers Face with API Documentation

Claudiu
Claudiu
bits and pieces of documentation & marketing 👨‍💻

This article will outline five most common API documentation questions technical writers might have. It will also provide the answers to those questions.

Application programming interfaces (APIs) are a popular modern-day software component.

A set of definitions and protocols for integrating applications, APIs allow different pieces of software to connect with one another.

Have you ever shared a YouTube link via WhatsApp? That action is only possible because of APIs.

Given the prevalence and complexity of APIs, it’s advisable to maintain documentation on them.

However, this isn’t always an easy task, and technical writers might ask themselves some questions in the writing process.

This article outlines the five most common questions related to API documentation and, more importantly, provides the answers to those questions.

So if you’re interested in learning more, keep reading.

What Tools Will I Need?

Your technical writers could conceivably use any documentation tool to create API documentation.

Any word processing software will work—even Notepad. However, the end result probably won’t be a high-quality document.

Simpler documentation tools, while helpful, lack specialized features for composing API documentation.

As such, it’s worth investing in specific API documentation tools to make the writing easier.

The documentation platform Archbee is a good example, as it’s evident the tool was designed with API documentation in mind.

For instance, Archbee supports autogenerated API references using OpenAPI or Swagger specifications.

Have a look:

Open API swagger block
Source: docs.archbee.com

The user-friendly interface makes it easy to execute API requests, and the feature will help you understand endpoints in the browser.

However, if your APIs aren’t using a standard, Archbee offers an in-house widget to describe API specifications.

The widget can describe cookies, parameters, request structures, response structures, and more.

Here’s an example:

API Endpoints
Source: docs.archbee.com

The widget is very adaptable and can describe any type of HTTP endpoint in detail.

Archbee is an excellent solution for documenting the APIs that have been developed.

However, there are also tools that help employees write the documentation before even beginning development.

This is how Apiary functions. This resource creates a mock API server to be continuously built and tested until developers have what they need.

In other words, Apiary helps technical writers create extensive API documentation first, postponing the actual coding until the end.

Here’s the tool in action:

How Apiary functions
Source: Business Process Incubator

The right-hand side displays what clients and servers are interested in, whereas the left one offers plain-language visibility into the API.

With Apiary, you’ll create detailed documentation before the API is even built, significantly easing development.

Archbee and Apiary are geared toward manual code documentation. But if you’re short on time or need to document a large codebase, there are also several documentation generators.

For example, apiDOC automatically creates documentation from API annotations in the source code. To fully utilize the tool, just ensure the comments follow the correct conventions.

Here are their comment guidelines:

apiDOC comment guidelines
Source: apiDOC

If you’re nearing a deadline, you can simply zip through the source code and add the relevant comments where necessary.

Then, apiDOC will do the rest of the work for you and automatically generate HTML documentation.

Who Will I Be Writing For?

APIs are built, deployed, and maintained by developers. Consequently, it’s safe to say they’re the most frequent readers of API documentation.

However, contrary to popular belief, they’re not its sole visitors. Despite their technical construction, APIs still impact all their users, not just developers.

As a result, you can expect a varied audience for your API documentation.

Here’s a brief overview of the possible reader profiles:

API Documentation Audience
Source: Archbee.com

The most common visitors will be developers simply because they have the most direct contact with APIs.

You can also expect decision-makers trying to gauge if your API is a viable solution for their business needs.

Finally, more casual observers might also read your API documentation. These include technical writers, journalists, or anyone generally interested in APIs.

Considering this variety, creating content for each audience type is essential.

Developers will require technical code samples, decision-makers will want use cases, and observers will appreciate non-technical explanations.

However, of the three, developers will likely be the most common readers of the three. That being said, developer is a fairly broad term.

Software development consists of multiple professions under the term developer, including Frontend developers, Backend developers, Game developers, and more.

Furthermore, each profession can further be segmented. Jason Hilton lists some other categorization criteria:

Likely there will be some criteria that would directly influence the sorts of developers who could become potential users of the API. Such criteria might include prerequisite technical knowledge, such as coding languages, platforms, or protocols, or else might entail non-technical factors, such as location.

It is vital to consider these criteria when writing API documentation.

For example, it’s probably not a good idea to suddenly delve into the corresponding backend PHP databases if you're explaining custom CSS options.

Instead, tailor each article to a specific developer profile relevant to the subject matter.

The Google Maps API documentation is an excellent example of this. Take a look:

Google Maps API documentation
Source: Google

The text immediately highlights the prerequisites for understanding the documentation.

Any developer unfamiliar with JavaScript and object-oriented programming concepts will know right away that this document isn’t for them.

It’s not a bad idea to incorporate a similar disclaimer while writing your API documentation. Use the top of the page to indicate the article’s intended audience.

That way, your documentation should reach the developers it was created for.

Must I Know Programming Languages?

API stands for application programming interface—a software intermediary serving as a contract between two applications. You can tell just by its name that it’s written in code.

Consequently, a technical writer must be able to read the code to understand the API. Knowledge of programming languages is therefore required when writing API documentation.

The only question is: how much knowledge?

Technical writers do not have to possess the same exhaustive coding knowledge developers do.

Developers learn programming languages on a detailed enough level to write code and build software.

Technical writers, on the other hand, only need to know enough code to read the software. Not maintain it or make any changes to it—simply understand what they’re looking at.

Or, to quote Adam Wood’s assessment of necessary coding knowledge:

Quote of Adam Wood’s assessment of necessary coding knowledge
Illustration: Archbee.com / Source: hack.write

For technical writers, bad coding skills are more than sufficient. Even bad coding skills allow them to read code, which is more than enough to compose quality API documentation.

The question then arises: what programming languages to learn?

A good place to start is to look at the current most popular languages. Here are CodingNomad’s findings on the topic:

The 10 Most In-Demand Programming Languages
Source: CodingNomads

As you can see, these were last year’s most sought-after programming languages, according to LinkedIn’s job postings.

Python, Java, and JavaScript take the top three spots, followed by C and its variations.

You should have a rudimentary knowledge of at least one of these languages, as they are sure to appear in your scope of work. Here's a nice blog post about day in the life of a technical writer.

Just knowing a single language is guaranteed to facilitate your workload.

If you’re unsure how to learn these programming languages, plenty of courses and boot camps are available online to help you out.

For example, Udemy offers the following program:

Udemy offers the following program
Source: Udemy

This course is designed with technical writers in mind and should teach all writers coding basics.

Furthermore, it emphasizes JavaScript—one of the popular programming languages mentioned beforehand.

Even if the program above isn’t to your liking, there are countless other courses for technical writers. You’re bound to find one that suits you and teaches you the bad coding skills you need.

What Sections Do I Need to Include?

API documentation is designed to facilitate API use. To achieve this aim, technical writers should prioritize certain non-negotiable information in every API document.

For example, changelogs are useful but not as helpful as code samples or HTTP requests.

So, what are these non-negotiable sections? A survey by SmartBear can answer that:

Top 5 most important things you look for in API documentation
Source: SmartBear

These findings rank the elements developers most appreciate in API documentation.

As such, try incorporating at least the top half of the chart in your texts—developers will greatly appreciate these sections.

Examples are the most helpful, as they showcase the API’s capabilities, demonstrating real-life use cases. In some documentation, they’re even interactive.

For example, Spotify used its Web API to build a demo that searches for an artist and plays the first 30 seconds of an album’s first track.

Have a look:

Spotify using Web API
Source: Spotify

With this preview, developers can clearly understand the potential of Spotify’s API. Furthermore, the interface is interactive, allowing for detailed and in-depth exploration.

Another essential API documentation feature is a status and error glossary. Developers must understand the API’s behavior, and status codes are the best messengers.

Here are Clearbit’s status codes:

Clearbit’s status codes
Source: Clearbit

A possible status overview is invaluable, as developers will always know precisely how the API responded.

However, in case anything goes wrong, they’ll also appreciate error codes. You can see Clearbit’s below:

Clearbit error codes
Source: Clearbit

This glossary details all possible error codes, which is a great help for developers. After all, knowing the cause of the problem is the first step to fixing it.

The third most sought-after API documentation feature is authentication information.

A process that validates the identity of the user trying to make a connection, authentication is one of the first steps for using an API.

Given the procedure’s importance, authentication information should be described in great detail.

For example, Twitter does a great job:

Twitter Basic authentication
Source: Twitter

This text outlines all the authentication steps and even provides a code snippet to better understand the process. No developer should have any trouble accessing Twitter’s API.

These three elements—examples, status and error codes, and authentication—are the most requested sections of API documentation.

However, for a complete list, refer back to the SmartBear survey.

How Do I Start Writing API Documentation?

Each writer’s greatest enemy is the blank page, including when writing API documentation. However, there are a few methods that can help you get started.

For example, this Quora user offered the following advice:

Quora user offered the following advice
Source: Quora

To write high-quality API documentation, you must first familiarize yourself with the API. After all, your document will be the authority on the API, containing all details regarding the program.

For such a high-level document, you’ll have to be an expert on the topic.

A good starting point is to examine the software yourself, taking a deep dive into all its functionalities. That way, you’ll learn the API inside and out.

If you have any questions during this examination, don’t be shy—contact the developers. They’ll share their knowledge, and you’ll walk away with new insights.

After educating yourself on the API, here’s a good next move:

Next move after learning about API
Source: Reddit

You’re not the first person to write API documentation. Countless technical writers have done so before, and most of their texts are publicly available.

So, why not see how they’ve completed the task?

Examining others’ API documentation allows you to explore how APIs are typically presented.

Furthermore, you’ll likely notice patterns and structures that might work for your own API documentation. Such examples are excellent sources of inspiration for your API texts;

After completing your analyses, you can start writing your document.

When doing so, it’s essential that the text answers the following questions:

Questions to answer in your API documentation
Source: Archbee.com

The API documentation should explain the API’s value and detail how users can benefit from it.

Furthermore, there should be extensive information on the different tools and endpoints.

It’s also helpful to include a Getting started section—that way, developers know what their first steps should be.

Don’t forget to explain the features well; readers should know every API feature and what they can be used for.

Finally, users will be interested in the API’s security and how the program is protected.

Keep these five questions in mind while writing, and your first API documentation will be a huge help to developers.

Conclusion

APIs are an invaluable part of software and are nowadays so prevalent that the average person interacts with one at least once a day—often without even realizing it.

Because of their importance, it’s advisable to create comprehensive API documentation.

Such detailed texts will facilitate API use, and developers will have a much easier time interacting with them.

When composing this complex documentation, technical writers should prepare themselves by asking the right questions.

What sections should the documentation contain? Who is the target audience?

The answers to these 5 questions technical writers face with API documentation will guide technical writers and help them compose first-rate API documentation.

We designed Archbee with technical writers in mind. Experience the full set of features with with our free 14-day trial.

FAQ

Frequently Asked Questions

What is an API and why is it important to maintain documentation on them?
Expand FAQ

To start writing API documentation, first, understand the API's purpose and intended audience. Then, explore the API and take notes on its functionality and features. Use these notes to create an outline for the documentation, including information on endpoints, parameters, responses, and any authentication or error messages.

API is an acronym for Application Programming Interface. It is a set of definitions and protocols that allow different software components to connect with one another. They play a crucial role in facilitating software interaction, with examples of their application being actions like sharing a Youtube link via WhatsApp. Because of their complexity and prevalence, maintaining documentation on APIs is advisable. Well-structured documentation can make the use of APIs easier, especially for developers.
What tools are useful for creating API documentation?
Expand Button

While having knowledge of programming languages can be helpful, it is not always necessary for writing API documentation. As a documentation writer, your main focus should be on understanding the API and its features, as well as being able to communicate that information clearly and effectively to the target audience.

Technical writers can use any documentation tool to create API documentation, but platforms like Archbee and Apiary which have features specifically designed for API documentation are advised. Archbee supports autogenerated API references using OpenAPI or Swagger specifications, and has a user-friendly interface that makes executing API requests easy. On the other hand, Apiary creates a mock API server for continuous building and testing, facilitating the creation of extensive API documentation. For large codebases or times of crunch, documentation generators like apiDoc can prove helpful.
Who are the intended readers of API Documentation?
Expand Button

The tools you will need to write API documentation include a text editor, version control system, and a documentation platform like Archbee. You do not need to know programming languages, but having some knowledge can be helpful. With Archbee, you can create, organize, and publish your API documentation, collaborate with team members, and track changes with version control. Using a documentation platform can make the process easier and more efficient.

While developers have the most direct contact with APIs and hence tend to be the most frequent readers of API documentation, the audience can be varied. Decision-makers may read it to gauge if the API is a viable solution for their business needs. Additionally, more casual observers which include technical writers, journalists, or anyone generally interested in APIs might also read the documentation. Consequently, it is important to create content catering to each type of audience.
Is knowledge of programming languages important for writing API Documentation?
Expand Button
Knowledge of programming languages is essential for writing API documentation, as technical writers need to understand the code to accurately document the API. However, unlike developers, technical writers do not need exhaustive coding knowledge, rather, they just need to know enough code to read the software. Familiarity with popular languages like Python, Java, and JavaScript can prove particularly advantageous.
What are the essential sections that need to be included in API Documentation?
Expand Button
Important sections of an API document include examples, status and error codes, and authentication information. Examples are particularly appreciated by developers, as they showcase real-life use cases of the API's capabilities. Status and error codes provide insight into the behaviour of the API, facilitating problem solving. Authentication, which is one of the first steps for using an API, is another crucial element that should be thoroughly explained in the documentation.

đź“– Table of contents

Answer questions instantly

Create and share documentation that answers questions instantly with Gen AI

Discover Archbee

Receive documentation and technical writing tips & trends — our newsletter

Join 5000+ people from around the world that receive a monthly edition of the Archbee Blog Newsletter.

Read more in

Documentation