5 Questions Technical Writers Face with API Documentation

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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.

‍

FAQ