Robert's Rules of Order for API Documentation Writing
The following is a set of guidelines for writing API documentation. API documentation writing is an exciting field that doesn't get much attention, respect, or admiration. 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. In practice, it's an art. The following guidelines can help.
They're called Robert's Rules of Order for API Documentation Writing. You can call them Robertisms.
[Home] [Writing samples] [LinkedIn]
By Robert Delwood
A lead API documentation writer
- Always be a beginner. The secret of API guides is to always be able to view the documentation as a beginner or as someone reading it for the first time would. Many managers think that anyone working with APIs will be sufficiently advanced that you can skip foundational material. They're wrong. Don't skip anything. There are enough kinds of programming that you can't assume everyone knows everything. A programmer skilled at C# or Java may not know npm.
- You're documenting it for yourself. Write the document explaining it to yourself. Pretend it's reference guide that you need for your job, and include details to that level. For example, consider it a procedure that you're only going to use once every three or six months. After three months you may remember general ideas but you're going to forget little details. It's those little details that matter the most. After six months, you're not going to remember even the name of the application. Besides, if you don't know what it is, or you don't know what to do next, and keep in mind you're in an ideal situation having all the developers around you, it needs documenting. If you have trouble with something, they're going to have the same trouble. Stop and document it immediately. Don't be afraid to deviate from the schedule, or to add additional pages in order to document things you don't know.
- Remember your first time. For most people, they only do things for the first time once. API documentation writers need to learn do things as if for the first everytime they do it. Remember what problems you encountered, what frustrated you, and how you solved the problem. Document all that.
- Appeal to their laziness. To be loved by your programmers, you have to appeal to an emotion. That's not admiration or respect. It's laziness. Programmers are inherently lazy. They like doing things only once. Do things that saves them time. This means to provide code to copy. The shorter they're on page, the more they'll like you. Put common reference material above the fold, so they don't have to scroll down. Understand that an API reference guide isn't just instructions, it's a code repository. Make a good enough code sample, they'll be back many times to copy it because they won't have to remember it.
- Go step-by-step. In documents other than the reference guide, include step-by-step instructions.
- Know what you know. This is the most important rule. You have to understand the things you know. This is when you assume to know things that the audience may not. This happens a lot in horror movies when the escaped intended victim runs into the small town sheriff and then starts incoherently saying things like aliens, ray guns, and SueEllenBeth. We the audience know exactly what he's talking about because we just saw it on the screen. Cletus, the small town sheriff, has no clue. He needs context. Too often, writers make assumptions and will leave out important information or steps just because the writer knows what to do next. When you review procedures, notice the steps you're actually taking and see if you're not including steps just because you know to do those. Those extra steps need documenting.
- Know what you don't know. This is the opposite of Know what you know. This time, the audience may know things you don't. As an example, I was reading a weather API and one section started to use terms I didn't know. Perhaps the audience did and it made sense to them. Actually, they probably didn't either, I think it was just a poorly written section. But you get this point. This doesn't come up as much in our technical writing, but it's possible to write technical material even on things you don't know anything about. Keep what what you don't know in mind, and learn terms.
- Know what they don't know. This is the second most important rule. You have to understand what the readers don't or won't know, and then include that information. Both of these steps are easy to overlook because of the familiarity the writer has with the material. These compliment the earlier ones. Keep those in mind Always be a beginner, You're documenting it for yourself, Remember your first time and you will have an expert understanding of what needs to be included.
- Your boss is wrong. I say this because few bosses have managed an API documentation writer, much less a team. Those who don't listen to their writers, base decisions on their limited programming or API experience. But we're not here just to follow orders. We're here to give our experience and insight. I remembered something I once read. That an API documentation writer owes his boss not only his industry but his judgement. And he betrays his boss if he sacrifices it to his boss' opinion.
- We're here for their convenience, not ours. Do as much for them as you can, even it's hard for you. We're here to make it as convenient as possible for them, so they have a good experience. This means writing code examples that include error handling, and type checking. Collect material in once place (like enums, objects, and return values), add links rather than "see the documentation."
- It's about the code. APIs are all about the code. Why would it be anything otherwise? So it makes sense to include as much code, as many examples, snippets as possible. Every call should have a code example. You will also need to know the jargon, technical terms, and even their humor. To talk with programmers you have to know as much about programming as possible. They will spot misused or miscast terms, and you will lose credibility with them.
- Examples are everything. This can't be overstated. If I thought I write an API reference guide using only code samples, I would. Use code samples for each call. You can use multiple code code samples. For example, when introducing a call, provide the smallest example possible so they can copy and paste immediately. They'll change the parameter values afterward to their own needed. The provide a comprehensive sample showcasing that call only. Finally, include a practical example that uses that call but in a larger context that solves a problem. My favorite page on MSDN was one that explain drag and drop programming. There was a trick to it in that two mechanisms had to work in tandem from the start, and writing that scratch was difficult to debug. This page had one of the most perfect examples I've seen. With almost no changes to the code, you could copy and paste it into your project and it compiled the first time. I bookmarked that page and went to it everytime I needed drag and drop. Which was often, because it was so simple, I wanted to use it a lot. This is a good example of a good example. Let programmers come back to the documentation for code samples, just not for reference material. Unfortunately, since it was such a good sample, Microsoft has since removed the page, but in a rare showing of foresight on my part, not before I copied the page myself.
- You're never done writing. Edit, edit, edit. Always review your work. All the time. For ever. The more you review, the better it'll be. First, it finds grammar issues. Second, since you know more today than yesterday, add, update, or correct material. Go back to material after three months. By that time you would have forgotten minor details, details that matter to the programmer. But it won't be so long you've forgotten everything. There's nothing wrong with changing your mind and changing the code.
- Review relentlessly. This is similar to never being done with writing but review procedures relentlessly. That while you write them, go back after a few days, weeks, or month. But it also means check them even as you just pass the page. Bugs are insidious and more are them are there the more you look. Tweak the text. Bosses will tell you not to do this but ignore them. Make the documentation better every chance you have.
- We're client advocates, not our developer's advocates. You're paid by the company but you work for your clients. API documentation writers are in a unique position to advocate for the client. We have an outside objectivity that developers, the UX team, or even the PMs don't have. The developers, for example, are too close to the code, and too focused on it to always see the problems that the client sees. As we document the APIs, if you see something that doesn't make sense, isn't clear, or you think needs to be changed, write a ticket and get it fixed. One example is that I think all APIs should be case insensitive, and I opened a ticket to always apply that to true/false. That's a detail client programmers aren't always going to do and will mess them up. Another example is error messages. Messages must be clear to the user to include the error, type, exact location, and then offer a suggestion about what to do next.
- If it's not already broken, then break it. Writers in general, and API documentation writers in specific are put upon groups, and we don't get the tools we need. That means if we're not given tools, we have to demand them. Therefore, complain relentlessly and annoyingly to our tool companies to fix bugs, and for us to suggest changes. We need to reject status quo tools and companies and expect them to write ones that fit our most unique needs. If they do not, then we need the community to step up and create new ones. There is no reason we have to work with status quo or substandard tools.
- If I don't like it, it's wrong. We API documentation writers are the experts about API documentation writing. We are expected to correct incorrect things. Therefore, if it's not right for us, it needs to be changed.
- If I like it, it's right. The corollary.
- Everyone works for me. I need information. They have the information I need. I'm going to get it from them. Don't be afraid to ask people for information, especially if they are from another group. Don't worry about formal lines of communications. Of course don't be rude about it, and understand everyone's busy, but feel free to ask for information. This widens your network, gets different perspectives, and get introduced to even more people. The wrong is in not getting the information.
- If you're good, you'll fail 99% of the time. Always try new ideas. If you're good, you'll fail 99% of the time. But you'll get an idea that works. And maybe not the original idea but an idea derived from that idea. That's the idea. And yes, status quo writers fail 100% of the time. That is, if they try only two ideas and those fail, they failed 100% of the time and have nothing to show for it. If you try a 100 ideas and one succeeds, you win with a 99% failure rate. Personally, I'm lucky if I get as high as one in a 100, but I think I eventually find what I'm looking for.
- There's no process so simple that it can't be made complicated. Don't do that. We earn our value by making things simple, not by inflating ourselves by making it complicated. No Machiavelli here.
- This is technical writing. We shouldn't have to guess what it means. Be explicit and be clear. If it's not both, then rewrite it.
- Similar items should have similar behavior. Consistency is good. If two items are similar, they should act and read similarly. For example, for toggle flag parameters, all of them should read like "Indicates if the item can be downloaded. If true..., If false..." and not have another one say "Yes= you can download, No means the user can't copy the file." Quiz: Spot the number of inconsistencies in the last example.
- Redundancy clarifies meaning. Repeating text confirms information for the user. This is not advocating having documentation in two places. This advocates the the button name, the subsequence dialog it brings up, and the text description on that dialog repeat the same title or purpose.
- Be clear on acronyms. Acronyms are tricky in that some are so obvious that they seem not to need an explanation. Others may be obvious only to experts. Consider spelling out them on first occurrence of the page. For example, the Control Center iOS page made a reference to MDM. The defense for not spelling it out was that anyone on that page would just know what it means. That's a poor excuse, and borderline arrogance on our part. Spell it out.
- Have neither shame nor dignity. Either one just slows you down. Get the information any way you can. You have no shame so that you ask anyone anything, look around the network, or snoop wherever you can. You have no dignity so say "I don't know." Writers in specific, but every one else too, want to be seen as experts in everything and don't need to be told anything. We're not, and we shouldn't. Let people talking give you their perspective. It'll make the product better.
- You know exactly what I know. Everything I know about a given topic is going to be documented. If there are errors or omissions, it's because that was my understanding of the topic at the time I wrote it.