By Robert Delwood
API documentation is an often overlooked component of API suites. This kind of writing is a specialty within technical writing because of its dependence on development. Schools and universities don’t teach it, training for new API documentation writers is sporadic, and companies do not always support them. Starting out as an API documentation writer ranges from intimidating as worst, to just unfamiliar. This paper addresses issues in becoming an API documentation writer, discusses the skills, and sets the expectations.
We need you.
We need API documentation writers. The fact is simple: We have more APIs than writers to explain them.
There are about 2000 new APIs a year for the last eight years with no sign of leveling out. At the least, that means 2000 new API documentation writer jobs years, and we’re not recruiting them.
Better stated, we’re not doing a good job training them. Perhaps for several reasons.
For whatever reason, there is an API documentation writers gap, and we need to address that.
So, what is an API documentation writer? Simply put, it’s someone who documents APIs. That’s not the glib answer it seems. What is an API? and Why does it need documentation? are the better questions.
For the first question, What is an API, we need to think about what programmers do. Programmers program. That is, they write applications and libraries. If the actual code were distributed to everyone, documentation might not be a problem, because we could all see for ourselves what the code does. But that’s not the way it works. They distribute compiled code in the form of executables and libraries. These are not discoverable. That means programmers can’t just load those distributables and see what calls they contain, or what their parameters are. Even if they could, they couldn’t find why anyone would use the call, let alone know about the caveats, warnings, or special notes.
For the second question, Why does it need documentation? if a programmer gets a math library file, users would have to be told everything about it, including the library name itself. For a few calls, this might be useable although annoying. A few hundred calls become prohibitive. The same holds true for Web calls. Users have to be told which calls are available, the format to call them, parameters they use, values and limits for those parameters, and special notes about using them.
For example, many think a REST, or a Web, request is simple. Indeed, some are. Paste the following command into a browser and you get the current position of the space station: http://api.open-notify.org/iss-now.json. While you need to be told what the request is, you don’t really need documentation for the results.
{
"iss_position": {
"latitude": "18.5699",
"longitude": "52.9005"
},
"timestamp": 1583013018,
"message": "success"
}
In contrast, try using Google Maps, Amazon, or eBay APIs without documentation, and taking the first step is all but impossible. The first statement to doodle in your notes margin: The documentation is the product.
Who then is best to write the documentation? There are three candidates.
On one end of the programming spectrum is the obvious choice of developers themselves. After all, who better knows the code than the people who write it? While that’s true, in practice, it is rarely a good idea. Developers are famous for being bad writers, at least in technical writing terms. To be fair, there’s possibly several reasons. It’s not their priority, meaning they aren’t assigned the time and responsibility. It’s not their interest. Or, they might not good writers. Don’t judge but also don’t make a fit where there isn’t one.
This doesn’t mean that developers shouldn’t write some documentation. In a world with Git, YAML, and language tags, developers need to document their calls enough for the writers to get the idea, and also supply information about aspects of the call that aren’t obvious. I ask our developers to give us a fighting chance. Having them supply notes shouldn’t be burdensome.
On the other end of the programming spectrum are technical writers. This is the most likely group that new API documentation writers will come from. I’m not going to detail the skills set of technical writers here. However, the notable trait is that they typically have little to no programming experience. That becomes a challenge we have to address for a role that works closely with developers. It’s a challenge but not a blocker. One of the most common ways that writers become API documentation writers is that they simply get forced into it, and great documentation still gets created. The good news is that some programming experience is always better than less. That means, they can learn along the way. The second statement to doodle in your notes margin: Not having programming experience isn’t blocking.
As the name implies, this is a combination of being a technical writer and a developer. In the past, they had been developers who switched to technical writing. In the present, they are technical writers who learned programming. They’re coming from different ends of the programming spectrum, but no matter.
They’re seen as developers. They can speak the jargon, read and write code, write their own examples, and can sympathize and empathize with the client developers. You know you’re in with developers when you start getting free lunches with them.
They’re seen as technical writers. They bring clarity, structure, and explanation to the documentation.
With developers on one end of the programming spectrum, and technical writers on the other end, then programmer-writers are everywhere else on that spectrum, which is a wide berth. The programmer-writer is the person you want to write the API documentation. This is also the group you want to be in.
The best way to explain how to get started with API documentation is to understand the expectations. Many explain this by describing their responsibilities. But if you meet the expectations, everything falls into place.
Honestly, how can it not be? You’re working with programmers, writing about programming to programmers, and even wanting the word programmer in your title. Another statement to doodle in your notes margin: The more you know, the better you’ll be. That means, any point along that spectrum is good. Writers without programming experience are valuable. But writers with more experience are more valuable. If you understand you’re entering a new skill set and take the craft seriously, you’ll get the experience along the way. But more on that later.
If you don’t understand it, by definition, you need to document it. This is the best part of the job and it’s where you learn the product. Anything you don’t understand, stop and document it thoroughly. Write step-by-step procedures, define each term, or write an article in that you pretend to explain that concept to a friend.
I’m talking about the client developers. Our job is to make their job easier. Writing a reference guide isn’t the task, a computer can do that, or worse yet, the developers. Our job is to make it so clear that the clients do not have any doubts about anything along the way. That’s a tall order. It means to explain every term. Include samples. Show every value, where those values come from, and an example of the value. Sometimes just seeing an example is enough. Instead of linking to a table, inline it to the page so they don’t have to go clicking off somewhere. Write code that does the hard part for them. The more we do upfront, the less they have to do themselves. That means they’ll like us more.
I’m talking about our own developers. The truth is that we’re annoyances to them. They have to stop what they’re doing to answer our questions, and to review our writing. However, it’s a garden variety annoyance because they know they have to do it, and that it’s in everyone’s best interest. We get to be special annoyances when they have to answer questions that we should know. (https://www.youtube.com/watch?v=T3dDRnTults). They won’t like us.
We’re hired to take tasks off their hands. We need to know the material, write in terms so plain that anyone can understand it, write code examples (and useful examples at that), and document procedures and how to articles. These are all tasks that they would have to do themselves. That means we have to learn this on our own by reading their specs, their code, and their examples. In short, we need to be seen as saving them time. But that takes effort on our part.
We may be paid by the company but we work for our clients. The documentation is meant for our clients, and that means it has to be clear, understandable, and make sense. This last item, what makes sense, is where programmer-writers excel. We have the objectivity that the developers do not. If there’s an onerous process, an obviously misnamed parameter, or calls and requests that don’t do what they claim to do, push back on the developers and make them change it. However, all this requires a certain amount of confidence, if not arrogance. Whatever it’s called, it makes for a better product, and that can’t be argued.
Other people have information. You need that information. So, get it. So many times, technical writers are sandboxed and feel, or are even told outright, not to go outside of that. Remember, we are working for our clients and anything that gets them correct or accurate information is inarguably a good thing. The entire company is your resource, so feel free to approach anyone.
Get the information however you can. Period. Too often, writers want to feel they know everything and resist being told anything. Avoid being that writer. Don’t be prideful or ashamed to say you don’t know. If a developer wants to tell you something, let them tell you. If it’s new, you come out head. If you heard it before, there will be one new fact, or a new perspective. When the accolades about the documentation start rolling in, no one is going to remember the questions you asked to get there.
If I thought I could write an API reference guide just using examples, I would. Examples are important. They have that A-Picture-Is-Worth-A-Thousand-Words thing going for it. It also allows copy and paste, one of programmers’ favorite things. They range from one line of code (showing the call or request), to multiple lines (if it takes more than one statement to get the results), to comprehensive examples (showing how the topic is handled through a series of calls). Examples need to be practical, and show what they report to do. They may need to be set up, having input or output values. A line by line explanation may also be needed.
Beyond simply showing the code, you want to have code so impressive that they come back to the page to copy the code. Some procedures are complicated or so involved that rather than rewriting it, just be able to copy it from someone who’s done it already.
Learning a computer language seems intimidating. Many go to a four-year school, and others spend years with the craft. However, for our purposes it doesn’t have to be like that. Of course, you’ll have to learn the language, and there’s no shortcut to that. It’s more about how you learn (books, videos, online courses, in person courses), time, and experience. However, you can leverage what you learn. What you do with the language along the way is more to the point. While learning a language, keep the following guidelines in mind.
I’d say that 80% of each language is directly applicable to all other languages. For example, each language has the concept of the loop. There will be syntax differences but the vibe will be the same.
Even if you don’t know the language, you can almost always read the code and get an idea of what it’s doing. The same idea works for API documentation writers. It won’t help with writing examples, but to get the idea of what the call does, reading the code may help. Add in a little knowledge about programming, and it’s a good start.
This is the question everyone starts with. Indeed, there’s a genre of articles about this. They explain one language over another. While those discussions have value, don’t sweat the details. Make this as efficient as possible. I just said that concepts are common to all languages. But the obvious is learning a language your company uses. Even at that, it may not matter much. REST calls, for example, aren’t even language based. They’re more of a notation, and the developers call them using their own language like C, C#, Java, or Python.
Technically scripting is a programming language. The key differences are that scripting languages aren’t compiled ahead of time, like C# or Java is, and it does stuff real time. It’s the second difference that’s important here. JavaScript is run inside another application, like an HTML page. VBA, Visual Basic for Applications is Microsoft’s script for their Office suite. VBA allows you to record a keyboard sequences, called macros, and replay them. You can share macros with others. The value here is you can start being a programmer immediately, and you get to do useful stuff along the way.
Whichever direction you go in picking a language, make it useful. But I said that already. More importantly, it’ll push you to do even cooler stuff. The kicker is that you’ll want to use it. Learning a language for its own sake is tough to keep motivated. Doing useful cool stuff is exciting.
Armed with all these skills, the whole point of this is to get an API documentation writing job. For all the companies who have an API, and we’ve seen that they should have an API documentation team, the truth is, many companies still don’t. I can blame CEOs for their lack of vision, but that doesn’t help us right now. But there are a few ways to increase the chances. You will likely have to use more than one. For instance, you can apply for a position, but the first thing they’ll ask is to see examples.
The first is the simplest: Ask. Ask your manager to transfer to API documentation. They might not know you’re interested, and so never mentioned it. They may not think you’re ready, so you’ll let them know that, too. They may not even have an API documentation, so you’re letting them know you want the opportunity.
This the oldest and most obvious way, but apply for a job. Be aware, finding a listing is difficult. First, it’s not a common position. Remember? No one knows what this job is. So, look at the description for the word API. Third, recruiters stop reading at API, and assume you’re talking about development. For a frustrating experience, try searching for API documentation, and most of the hits will be for developers. Nevertheless, this has to be at least part of your job search.
Learning and knowing a language is actually two different skills. First, it’s learning a language. It’s how you learn it that’s the point here. Whether it’s a book, video, or on your own, notice how the material is best presented to you, and notice what helps make you remember it. There will be aspects you like, dislike, and things you would change in either case because you think it made learning better. Others will experience the same things in the same way, so remember that when writing to others. Then make that style yours as if you invented it.
Second, it’s knowing a language. With it, you can read and write code, prepare samples, and understand developer’s jargon. However, just knowing the language isn’t the point. In writing API documentation, you will never be asked to explain a for loop, or how to open a file. Those are all givens. Instead, you’ll need to use those to explain the product. Your samples may need a loop to create multitudes of objects from your product. The point would be to explain those objects and not how to loop, although knowing loops you would know to add perhaps an error trap for unexpected cases, and avoid the off by one error. Those would otherwise be newbie mistakes and detract from you as an author.
Doodle in your notes margin: Learn a language. It’s been pointed out several times, but still worth the doodle.
There’s nothing complicated about writing an API. At least there doesn’t have to be. At the simplest, it can be one call. Write a simple call and then explain it to someone. Create a library, a compiled set of calls often as a .dll file,
Write somebody else’s documentation suite. Use one of the many freelancing services, like Upwork or Freelancer. There’ll be several opportunities to look for. If not writing the suite outright, then reviewing an existing suite for grammar, clarity, and technical accuracy. Volunteering is another option. Find a product you like, such as through your hobby or interests, and sign up to help. At the least, go to their GitHub space and try writing a call description or edit a description.
The Web site The Programmable Web offers literally thousands of APIs. Look at those, as many as you can, and get a feeling about what you like, dislike, and how you would change them to make them better. No one API suite will be perfect, but there’s no law that requires you to accept what’s out there. I have a long list of things I don’t like and within my small power to change things, I do.