Photo by Jan Baborák on Unsplash

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…

Many see API documentation writing as technical writing. It’s not. Here’s why.

Image by Thanasis Papazacharias from Pixabay

Technical writing is often seen as being all the same. Any technical writer can be hired to write any technical documents. Think of software and software manuals. Writers look at their screens and document what they see. It’s true, there is that aspect, though that’s not the only aspect. This perception is at the core of the problem. There are different types of technical writing: Software, medical, and API technical writing.

Difference #1: It’s a Specialty

Medical writers will tell you their profession is about medical writing. It’s medical. API documentation writing is…

Photo by Marek Levak from Pexels

Documentation teams traditionally have not written software or developed customized software tools. Many companies consider those skills too specialized to relegate to writing groups, too costly, or do not see the advantages of automation. Many teams themselves just have never thought about programming, thinking such an effort may be out of scope or that the team does not have the proper skills. However, in this age of automation and convenient data access, there are significant gains to be made (such as better, cheaper, or faster in any sense of those words) by automation in support of documentation.

To help you…

Photo by cottonbro from Pexels

“The first sentence needs to be short and descriptive.”

For API documentation writing specifically, but also for technical writing in general, make the first sentence short and descriptive. It sounds so obvious but not everyone does it. This applies to the first sentence of any call, request, parameter, or any kind of description. It’s like an elevator speech for the call, much like “This call does X.” In one sentence, you give the readers enough information to determine if this is the right call for them. Technically, it gives enough information to determine if this call is the wrong one…

Can clients get started with your API in fewer than 30 minutes?


The concept of API documentation is simple, right? It’s a listing of all the calls and parameters, along with their descriptions. That describes an API reference guide. You ask, Isn’t that the point of API documentation? It might be, if that was all there was to it. The reference guide, which is just a listing of words and their descriptions, can be analogized with a dictionary. The fact is, you can’t learn a spoken language just from a dictionary, and you can’t learn a computer language from just…

Photo by Alex Azabache on Unsplash

I love a good board game. There are challenges, social interaction, and sometimes history to be learned. Yes, history. Almost everything I know about history and world geography comes from wargames. Who would remember Mongolia’s capital Ulaanbaatar (Ulan Bator), if it not for the fact it was the jumping-off place for Russian forces to battle the Japanese in World War II? Or that Roman triremes were Carthage’s naval nemesis? Or the revolutionary impact of “Stonewall” Jackson’s foot cavalry?

I believe board games have a unique opportunity to teach, especially if there is a historical aspect to them. I understand game…

Image by Free-Photos from Pixabay

Have you seen any rules lawyers lately? Well, I have heard rumors of them just like UFOs and Bigfoot and I believe the rumors about as much. But when it comes down to the wire, I like the accused much more than the accuser. This article is written for Advanced Squad Leader (ASL) but is applicable to all board games. Read on.

Like their real-life counterparts, rules lawyers are the people we love to hate. In ASL, the animosity runs even deeper. To call a player this is no small accusation. This person is the pariah in the ASL community…

The last painted portrait of Mozart, nine years before his death.

I’ll get to the point: He didn’t do it.

History books are capricious masters. It’s unpredictable who gets recorded and why. Asked to name the two most famous composers and Mozart and Beethoven come up. Rightly so, too. Asked to name a contemporary of Mozart’s, and Antonio Salieri immediately comes to mind. Salieri (1750–1825) is an overlooked genius. From 1774 to 1824, 50 years, he shaped and defined music. Specifically, eighteen-century opera, having written 41 between 1771 and 1804, in three languages. He was also one of the best and most sought-after teachers available. Mozart and Beethoven had him as…

OK, the title was an overreach. I don’t like their formatting.

To catch everyone up, MSDN (Microsoft Developer Network) is Microsoft’s massive online API, getting starteds, and everything coding-related repository. Don’t get me wrong. It’s an outstanding resource, more so since it’s free. But it’s not exempted from criticism. In fact, every page asks me if I like it.

I disagree with the API documentation formatting. To catch everyone up, API (application programming interface) is the list of calls for an application. It’s a sort of a dictionary for programming. The call components are explained in detail, such as the…

Robert Delwood
Lead API Documentation Writer

The following is a set of guidelines for writing API documentation. API documentation writing is an exciting field that gets respect and admiration from your friends and coworkers. But not much attention. That is, until programmers can’t get their application to work.

Many see the writing as mechanical, and that machine-generated documentation is good enough. It’s not. If you think about it, who writes the machine-generated documentation? In practice, it’s an art. Too many times, new writers are taught the mechanics of writing but overlook the point of writing. The point is to convey…

Robert Delwood

Programmer/writer/programmer-writer. A former NASA engineer, he made sure astronauts had clean underwear. Now, it’s API documentation and writer automation.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store