Image for post
Image for post
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…


Image for post
Image for post
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…


Image for post
Image for post

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

Introduction

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…


Image for post
Image for post
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 for post
Image for post
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.

Rules Lawyer, Come Forth

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…


Image for post
Image for post
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…


Image for post
Image for post

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…


Image for post
Image for post

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…


Image for post
Image for post

Robert Delwood
Lead API Documentation Writer

I advocate that writers rely on themselves for creating tools. This is more than just theory for me. I’ve been working with writing groups for more than ten years, helping them automate their processes. I’m a Microsoft Office programmer, which means I write applications that use Office tools. I’m familiar with what’s possible. Tools are any form of automation that helps writers complete their tasks. We think of this from a high level, such as Madcap Flare or Microsoft Word. In reality, we need low-level tools. …


Image for post
Image for post

All of our computers are going to crash in the year 292 billion and 1,970 AD, and no one seems to care.

Computers are very good at counting, but less good about how they count. That last fact should be downright disturbing. What that means, is that they can count, but they don’t know what the highest number in the world is. For all the advantages computers have, they do have a beginning of time, apparently 1970, and an exact end of time. That depends on the number of bits they can count on.

In computers, a bit is a…

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