Seven Skills You Need for API Documentation Writing…

12 min readMay 2, 2021

That you can use right now…to get your own work done…better and more quickly.

API documentation writing is a misunderstood community. From CEOs down to even technical writing managers, few understand what it’s supposed to do, and fewer understand how to do it. And that’s exactly the problem. You can’t go to college to get a degree in API documentation writing, there are few certifications, and on-the-job training is minimal. It’s more like a sink-or-swim approach, with people being thrown into the role and expecting them to figure it out as they go. None of this makes for a good documentation plan.

So, how you get jobs is a different topic and has to be covered separately. However, there are basic skills that you can learn now that apply directly to API documentation writing. These skills have common four points.

They will be used with API documentation writing. Get used to them now. Each tool will be slightly different of course, but get used to their format, notation, and style now when you’re not under pressure. You’ll have plenty of other things to learn once in the position.
They are skills that you can use right now. You may think they’re not useful, or you may think you don’t need any other tools. That’s dangerously narrow thinking. You’re not going to be using one tool. For starters, API documentation writer’s toolset can be said at best to the weak, at worse, inadequate. Get into the mindset of using a range of tools, and start using them now.
Learn expectations, not requirements. Too often companies present requirements about the position or product. While requirements have their place, they tend to scare people off, since they don’t meet requirements, or misrepresent the product. You can meet requirements and still not make the right product. It’s like seeing sushi only as uncooked fish. It’s technically correct but it completely misses the experience. However, if you meet the programmer’s expectations, and they’re happy with what they’re given, you’ve delivered the right product. Requirements be damned.
Learn the theory. After that, everything is just an implementation detail. Learn the concepts of how or why things work, you can always look up how to do it. For example…
1. If you learn looping in one language, you know that looping will be supported in other languages. You don’t have to ask if another language has loops. You can reference the syntax.
2. In another example, Madcap Flare users understand how Flare works. If you use Flare out of the box, you will get great results, because it’s a great product. However, if learn HTML, and you open up the HTML level for your changes. This expands what you can do. Learn XML, and you can do even more, since at the lowest level, Flare uses the same XML files that you can change. One step further, and learn that XML and HTML are just plain text files, and you open up your project to every tool on the market that changes plain text files. If you didn’t like the spellchecker in Flare, you could use another spellchecker to act directly on the XML or HTML files within the Flare project. The point is you will have so many additional options, and so many additional tools.

Backing up a step first to make sure everyone is on the same page.

What is an API? An API is a collection of commands that an application or server understands. For example, when you buy a printer, that printer comes with its own set of commands. An application such as Microsoft Word has to send exact print commands in order for the printer to understand. Likewise, when using a browser to search on Amazon, an exact set of commands, including perhaps search parameters, has to be sent to the Amazon servers.

Why does it need documentation? Simple: Their calls are not discoverable. That is, there is no way programmers themselves will be able to figure out, or to discover, the set of calls. Even if they could, there are still parameters, caveats, warnings, and other notes that need explaining. In short, a programmer has to be told what the commands are. Being told is the documentation.

Therefore, in a very real way, the documentation is the application.

If you are considering a move to API documentation writing, or thinking you might want to move to that later, here are some important skills. Even if you’re not considering API documentation writing, these are just good skills to know. You can use any one, or a combination as you like.

#1 Learn code

API documentation writing is about writing to programmers about programming. You need to know programming. Why would it be otherwise? But learning code may be for reasons different than you might think.

Learn a computer language. There are many sites and articles debating which is the best language. Don’t be confused: It doesn’t matter. 80% of all languages are in common. If you learn Basic, then Java, JavaScript, or C# are just modifications of Basic. That’s part of the theme. Learn the theory and everything else falls into place. After that, implementation is just details that you can look up.

On top of that, it doesn’t even have to be a language. It could be scripting, macros, or even automation tools. More on those later. The choice of languages doesn’t really matter although it can make life easier. If you’re working on a Web project, Java and JavaScript may be good choices. A computer application, then .NET like C# is good. In either case, Python is a reasonable runner-up thanks to its versatility.

There’s nothing scary about this and don’t let anyone let you think otherwise. Get a book or find a Web site, and just start walking through each example.

Knowing a language makes you sympathize with your users. You know what they know and you know their challenges. But just sympathizing with users isn’t good enough for us. We need to empathize with them. Read on.

#2 Learn about learning code

In learning a language, one of the factors is, well, learning the language. That means, how do you get information, and how best do you retain it? The medium is API documentation. They have calls they want you to know about, and they’re presenting it in a way they think is best. The only question is if you agree. During this process, be especially aware of how you get the information, and what you like and dislike about each approach. This isn’t about books vs. videos, although there is that aspect. It’s about each step. Which methods were most effective? Least effective?

Now, you’re empathizing with the user. You’re in the same place as they are for learning. The things you didn’t like, they won’t like. Conversely, the things you liked, they will, too. Develop your own styles. Avoid some things, keep using others, and in all cases, improve what you saw. There may approaches you didn’t like, but they have had small aspects you did. Take all those cases and change them to make them yours. But you would never have gotten here if you hadn’t learned the language.

#3 Learn to use code

The best way to learn a language is to use it. I said earlier that these “are skills that you can start using right now.” Find activities that let you do your job. It’ll keep your interest, get something useful, and push you to learn more about the language.

If you learn a language, write a program that changes selected text to all lowercase. That program should be about four lines. When I was working with Flare, I had an application that changed text to lowercase and replaced spaces with underscores. I used that to create anchors for the HTML. I then went one step further, and had the application create both the anchor tag, and the link tag. It was copy and paste after that to use the two tags.

Languages aren’t the only options. There are also macros and scripting languages. Both of these let you automate a tool by writing scripts and then running them later. DOS is still around. In fact, there are things you can do only in DOS, yet, and not through the Windows finder. Suppose for example you have a complex procedure, perhaps for archiving files after a project. You have to copy files from several folders into one, rename them, and zip all of them into a single file. You can do this by the command line. But instead of doing it in five separate commands, they can be combined into one single command.

This is used extensively in the API documentation community, so it’s a needed skill. Regardless, whether Windows or Linux, it’s something you can use right now. The following applications each have a scripting or macro capability.

Windows: Batch files, command line.
Microsoft Word/Office suite: VBA, macros (built-in/custom), fields, building blocks.
Mac: Batch files, command line.
Madcap Flare: Macros, build scripts, variable. Flare is built on plain text files, which opens a tremendous capability.

The second aspect is to push the limits of the code. In this way, you learn to dig deeper. This creates additional empathy as you find out what is needed to learn the details of a call. Using the macros and scripts you wrote in the previous step, make them do more, add detail, or add nuance to each call. This is a natural progression. You may want to add a save dialog box, be able to specify files to pass in, visually display a list of files, perform some sort of additional task. Some calls contain parameters that change the function slightly. For example, a file copy or move function. Some obvious questions come to mind:

Can you rename the file?
Do you specify the file name in the destination?
What if a file of that name already exists there? Is it overwritten? How are you informed?

Learn to anticipate questions and answer them ahead of time. Your readers will love you for that. In addition, chances are the file copy or move command has optional parameters for those, or the call’s documentation covers it. It’s your job to find that out. And it might be your job to make it better, in that you mention those to the developers.

The third aspect is to showcase what you’ve learned. An important task with API documentation writing is to show users what the call does, provide sample code, and perhaps instructions for them to do it themselves. In short, make them excited to use your calls. What you can do now is share your scripts with your colleagues. If it’s useful to you, it’ll be useful to them. In a direct way, a script for a group’s process can be used without modifications. In an indirect way, it inspires them to new ideas. My favorite part of an automation project is when the users start asking “Can you do this…?” They are coming up with the ideas now. That’s the whole point of API documentation.

#4 Learn the command line

DOS is not dead and Linux cannot be killed. The command line, that black window where you have to type everything, is still around. I know. It’s the 21st century, right? For Windows, it’s making a comeback. For Unix and Linux, it never went away. Regardless, in the API documentation world, it’s a fixture and you need to use it. As examples:

Git, the popular code management system, uses a command line. Yes, there are graphical applications that work around it, but ultimately, you’re better off just using the command line version.
Installer applications. Some applications are designed to be command-line only. NPM, Sudo, or OpenAPI CLI. You may not have heard of these, but they are used extensively in the API community.

What can you do right now to use it? You may already be using Git as a content management system. There is a popular movement called Docs As Code that treats documentation the same as source, including using Git.

Scripting was mentioned earlier, and that’s command line. In Windows, a batch file bundles individual lines of scripts into a single command.

#5 Don’t worry about tools

In the technical writing community, writers are closely associated with their tools. Many job requirements list tools, such as Word, DITA, Flare, Adobe suite, almost as if they classify people according to tools they know. Yes, the tools are important. However, a fundamental switch is that the API documentation community sees tools only as a means to an end. There are two reasons for this.

First, there are so few tools that you have to use whatever is available.

Second, there are so many procedures that you have to use during the day, and you use whichever tool can do them. For examples:

An OpenAPI (formerly known as Swagger) files. These are a standard in API documentation community, are just plain text files. Any text editor can modify them. Commonly, writers use what editors their developers use, perhaps Intellij, Visual Studio, or Swagger editor. Ideally, you want to be in a position to know enough that use could use Notepad to get the job done. After that, tools just become a device to get the job done.
Text editors like NotePad++, and ultimately NotePad. There may be other files, scripts, log files, database files, you need to open, look at something, or maybe change something.
REST calls. These are likely the core of your work, and will need to make REST calls, so you’ll use Postman or cURL, a command-line editor.
Compiling. You can use an IDE like Intellij or Visual Studio, or a command line, perhaps for compiling OpenAPI projects.
Databases. Most REST functions access a database. You may need to confirm some values, or even change data so you can test a call. An editor like Microsoft SQL Studio.
An image editor.
FTP to transfer Web files.
Markdown, HTML, CSS.
Word, for formatting tables.
Regular expressions (regex or grep). This is a pattern search, rather than a character literal search. Combine this with a multifile editor such as NotePad++, and you can search thousands of files at one time for a specific pattern.

Seriously, you can use almost all of these in one day. As mentioned earlier, the point is to know what the theory is, and after that, implementation are just details you can look up.

#6 Never say “I know that.”

The most damaging thing to say to anyone is “I know that.” It shuts down the conversation. When are you talking to a developer or a subject matter expert, let them talk. Even if you truly already know what they are saying, let them say it. This is for three reasons.

You probably don’t already know it.

There may be a different perspective or angle they’re leading to. They may have an additional use, additional information, or leading the story to a different place.

It shuts down future conversations. They may not want to be helpful in the future or find you hard to work with.

#7 Examples, examples, examples

Examples aren’t another thing, they’re the only thing. Examples are important in the technical writing world, but they take special importance in a programming world. They are used in three ways:

Individual calls.

An example call shows the formatting and parameter use. Developers love to copy and paste.

Call format.

The importance of call examples is that it shows the formatting and parameter order. Since all calls are texts, just having the syntax or even a description isn’t enough. As an example, the following is the DOS copy command, which is still relevant due to Windows batch file scripting. The syntax is:

COPY [/D] [/V] [/N] [/Y | /-Y] [/Z] [/L] [/A | /B ] source [/A | /B] [+ source [/A | /B]
[+ …]] [destination [/A | /B]]

That is hard to read and more difficult to make a useful call quickly. The examples make short work of that. And, they can just copy and paste the command they want, helping to make you even more well-liked among the developers.

Copy a file to a specified location:
Copy April_Report.doc c:\monthlyreports

Copy a file to a specified location, and change the file name:
Copy April_Report.doc c:\monthlyreports\2021_April_Report.doc

Copy a file from the non-current location to a separate location, and change the name:
Copy c:\currentmonth\April_Report.doc c:\monthlyreports\2021_April_Report.doc

Copy a wildcard group of files to a specified location:
Copy currentMonths*.* c:\monthlyreports

Copy three specified files to a specified location:
Copy April_Report.doc+ March_Report.doc+ Feburary_Report.doc c:\monthlyreports

Copy files, verify the copy, and automatically overwrite existing files:
Copy /V /Y April_Report.doc c:\monthlyreports

Copy three specified files to a specified location, verify the copy and automatically overwrite existing files, and specify the new file to be a binary file:
Copy /V /Y April_Report.doc /B+ March_Report.doc+ Feburary_Report.doc /B c:\monthlyreports

Code snippets.

Code snippets are multiline examples. Often, a call needs a setup, variable defined, or processing in a specific order. Snippets show that sequence.

Complete applications.

Too much of the time, writers are focused on individual calls. That is a good thing but it isn’t complete. Writing an application has several benefits.

It allows you to see the big picture. An individual call may return an array of records, but going through those records, collecting a list of names, for example, is something many writers haven’t done. Doing that lets you further empathize with the developers.

As with all code examples, it’s less work for the developers. They can copy the project and as always just change the sections or values they need to.