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 for them. …


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 API reference guide. In both cases there has to be more. …


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 themes. Not all games have to be historical, or even historically accurate. But when there is an opportunity, game designers should pounce. Board games in general, and wargames in specific, make a topic intimate for the players. Players get to study the map, know the units, maneuver, and battle on the actual terrain, even get to know the politics and limitations of the moment. …


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, bending rules to serve his sole purpose and then changing them again against his opponent. He looks for loopholes in the rules to exploit and to gain a nefarious advantage. He argues rules expertly and uses sophistry to set his point. …


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 a teacher, albeit at different times. He taught Franz Liszt, Franz Schubert, and Giacomo Meyerbeer. …


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 parameters, return values, caveats, warnings, sample code, things that aren’t obvious, and things you need to know about the call. It should be the single source of all truth for that call. However, the level of detail is subject to debate, and is a constant source of arguments within the programming world. I’m not going to talk about that here, but know that most of those conversations end with the writers saying something like “Oh, we didn’t have enough time.” Everyone understands that. …


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 information. …


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 single piece of information that a computer can store. It is either off or on, also called zero or one. That means a one-bit system can only count two: Zero and one. After that, it just repeats starting zero and one over again. This is the key concept to it all. When a computer hits the highest number in its universe, it starts over at zero. At least we hope it does, but more on that later. …


Image for post
Image for post

A Programmer’s Perspective

Senior Programmer-Writer

Tools will always be the weak link for writers. Not the high-level ones such as Flare or Framemaker, but low-level tools, ones that individual writers need to finish tasks. These tasks may be unique to each group or perhaps to each writer, from reformatting long lists of error codes, to collecting acronyms within a document, special or conditional formatting on tables, or repeating onerous sequences — a representative list is impossible to create. So, given the extreme diversity among writer’s procedures, it is unlikely we will get a comprehensive tool suite. The technical communicators community has not created these tools for us. …

About

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