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.
Write the document explaining it to yourself. Pretend it’s a 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.
Most people only do things for the first time once. We have to do things for the first time every day. API documentation writers need to learn to do things as if for the first time they do it. Remember what problems you encountered, what frustrated you, and how you solved those problems.
You have one document that both newbie and grognard read. That doesn’t mean it has to be equally weighted to each group. It means it can’t be weighted exclusively to one group. Complacence and management drive the focus to the experienced developers. It’s a natural thing to do. As you yourself get comfortable with the product, you make assumptions. That’s when mistakes start creeping in. Resist that. Include those who are new to your product and remember the problems you had getting started. Document all that.
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 save them time. This means providing code to copy. The shorter they’re on the 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.
In documents other than the reference guide, including step-by-step instructions.
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. As people spend time in their crafts, hobbies, or job, they naturally develop familiarity with the concepts along with lingo, jargon, or argot. These are specializations of the craft. This saves them the effort of explaining ideas they already know all the time. Likewise, other aficionados come to understand those terms and concepts. Those two people communicate effectively with each other. They both have the same secret decoder rings. The problem is, then, when people outside of that craft read the material. This is the very case of being a technical writer. Newcomers are not going to understand it. This is one reason I especially dislike acronyms. Jargon is not bad in itself. We just have to make sure we define those terms or concepts.
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.
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 you don’t know in mind, and learn terms.
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 complement 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.
Few bosses have managed an API documentation writer, much less a team. Those who don’t listen to their API documentation writers, base their decisions on their limited programming or limited API experience. As a result, they treat API documentation projects like tech writing projects. And they get tech writing project results, which are a disaster. These are not tech writing projects and you’re not going to convince bosses they’re wrong. But we’re not here just to follow orders. We’re here to give our experience and insight. I remember something I once read. That an API documentation writer owes his boss not only his industry but his judgment. And he betrays his boss if he sacrifices it to his boss’ opinion.
This means to define every term. Not some. Not most, many, a lot, or a copious amount. Define every term. This includes terms like what a document is. Nothing is beneath you. Define the difference between two similar items. When a distinction needs to be made between two items, you get to make up terms. The person who first made a watch that could be worn on the wrist, had the right to make up a new term: Wristwatch. There had been time-keeping devices before that, but now we needed a more precise term to describe it. Pick terms that describe the concept exactly, and use those terms consistently. The act of defining it means you learn the term, learn its context, and can speak knowledgeably about it. When you define a term, you own it.
I have two classes for API concepts: Common concepts, and obscure concepts. Common concepts are those likely to be already known to the user or reader. They still need to be defined somewhere. But when using them, they may not need a long explanation.
An obscure concept is one that the user or reader may not know. It may just be a lesser-known idea, or a concept unique to your product. When mentioning an obscure concept, also include one, two, or three lines about the concept. Define it right there. Don’t skip over it, don’t make them link to it, or look it up somewhere else. Add why you would use it, and an example of using it. This would be good for reusable text but include this for every occurrence. The idea is to help the user as much as possible with the least amount of work on their part.
As a simple example, the following is the Font dialog box from Word. All the items are reasonably understandable, except one. What is Equalize Character Height? I would call this an obscure concept and as a service to the reader, include a brief description. Even if other items do not have a description.
The “their” here are the audience developers. 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 one place (like enums, objects, and return values), add links rather than “see the documentation.”
The “their” here are the company developers. Do as much for them as you can, even it’s hard for you. We need to write the code samples, do our homework before asking questions, and generally save them time. Otherwise, we’re just causing work for them.
APIs are all about the code. 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.
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 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. Then 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 explains 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 every time 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.
Edit, edit, edit. Always review your work. All the time. Forever. 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 the 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.
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 months. But it also means check them even as you just pass the page. Bugs are insidious and the more of them, 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.
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 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.
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.
We API documentation writers are the experts in API documentation writing. We are expected to correct incorrect things. Therefore, if it’s not right for us, it needs to be changed.
I need information. They have information. 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 communication. 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 gets introduced to even more people. The wrong is in not getting the information.
The fact is simple, writers are annoyances to developers. Developers have to stop what they’re doing and answer questions they think are beneath them. Or review code they think they could do better in half the time. But all this is expected (https://www.youtube.com/watch?v=T3dDRnTults). They expect it. You expect it. You expect that they expect it. It’s a garden variety annoyance that everyone has to put with, and that everyone understands.
Where you lose points is when you ask questions that you should know, or cause them work. Do your homework first. Play with the code in the compiler, Google it, ask lower-paid developers, and then work up. Do things that save them time. Like writing the code samples, creating a list of exceptions, explain complex solutions simply.
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 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.
Don’t do that. We earn our value by making things simple, not by inflating ourselves by making it complicated. No Machiavelli here.
Be explicit and be clear. If it’s not both, then rewrite it.
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.
Repeating text confirms information for the user. This is not advocating having documentation in two places. This advocates the button name, the subsequence dialog it brings up, and the text description on that dialog repeat the same title or purpose.
Don’t use them. Just don’t use them. Acronyms are tricky in that some are so obvious that they seem not to need an explanation. But those are actually quite rare. That means, most won’t be well known to the readers, especially if they are unique to your product. For example, the Control Center iOS page makes a reference to MDM. WTH is MDM? Few are going to know what means. 1) Always just spell them out, on all occurrences, all the time. 2) Don’t even consider spelling them out on only first occurrence of the page. Keep in mind that users of an API reference guide may start reading on any page at any point. They’re there to read about one parameter from among many, or just one value for a parameter. They get to the page through a document search, an Internet search, cross reference, or just by scanning the page. The point is they’re not going to be reading sequentially from the top of the page down. In API reference guides, first occurrence doesn’t mean anything. This is also one of the differences a technical writer has to make for API documentation writing. But I digress. Back to my point: Bitch slap anyone who says readers will “just know” what an acronym means.
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 everyone 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.
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.
Elegant variation is the use of different terms of the same thing for poetic effect so that the reader doesn’t get bored. If you’re an aficionado of cheap romance novels like you know I am, you’ll understand. Technical documents can’t read like an amateur's use of a thesaurus. But we’re not a literary society. We’re like technical writers. So we have to use exact terms that mean exact things. And we have to use the exact term each time to refer to the exact same thing. Remember, I just said to define each term. Don’t refer to one item in several ways. For example: Put the documents in the folder. Delete the files in the directory afterward. Folder/directory, documents/files. And that’s at the most simple. No, no, no, no. Define a term, and absolutely use it consistently.
We’re introducing technical concepts and procedures. Be explicit. Use precise terms. No nicknames, cutsie names, short versions, or Latin. Be complete. Don’t use etc, or and so on when listing options. If those are only being mentioned, keep in mind it makes them more familiar with the terms.
Too often, technical writers are given lists of requirements, assuming that adherence to requirements is the definition of quality. That’s so 1985 Philip Crosby. You see this in job postings. Candidates need to know Flare, DITA, and REST or SOAP. All good things, true. But learn the reader’s expectations and meet those. What information they want and where they’re going to look is the goal. That’s the challenge, and fun, of API documentation writing. How you do that is just mechanical or rote details, and you can look up those up.
API documentation needs to give the reader confidence in what they’re doing is right, every single step along the way, also see This is technical writing. We shouldn’t have to guess what it means. Peace of mind is an intangible element that needs to be there. It’s like getting read confirmation from an email, a person nodding when you talk with them, or a sign in the middle of a path confirming you’re still on the right path.
Many issues have logical questions automatically attached. Some issues you find during research. Regardless, obvious questions come up. Likely, if you have questions, they will have the same ones. So anticipate those questions and address them in the documentation. Don’t make the FAQs, that’s just another place to make them look at. Inline them in the documentation.
Documentation has to be everything to everyone but that doesn’t mean everything has to be equal. The core text still has to be there for first-time readers. After that, they’ll cherry-pick the information that they need. Perhaps just a specific parameter, or a code example. You can’t have too much information. Don’t think that just because they only read it once, that it’s not valuable. Readers will skip over the information they don’t need. You’re not going to waste their time.