Getting Started in API Documentation Writing: Part 1, an Overview

by Robert Delwood, a Lead API documentation writer

Introduction

This is the first of three parts addressing getting started in API documentation writing.

There is a lot of confusion around becoming an API documentation writer. Many convolute the point by saying it’s about being a programmer. Others insist it’s knowing a language, and others still hone that point, arguing which is the best language to learn. While they are all right in some ways, it doesn’t have to be complicated. Don’t let anyone make you think you can’t get into it now. Yes, it takes work and, frankly, a little bit of luck. But not complicated.

The Three Keys

You should view API documentation writing as a continuum, as seen below.

On the right extreme is being an expert developer. On the left extreme is not knowing any programming.

The first key is understanding that farther to the right will always be more effective.

Very far to the right, very effective. Not so far to the right, not so effective. But not being to the right at all doesn’t mean being completely ineffective. Not knowing any programming is not an obstacle. It is a hindrance we just have to work around.

The second key is treating this profession as a craft.

This is the workaround to not knowing programming. Take the skills seriously, learn a little each day, and you will inevitably move to the right. That’s the place you want to be. You don’t have to have all the skills upfront on the day you start. Everyone’s heard of starving artists and starving artist sales. No one’s heard of starving craftsmen. That’s because craftsmen are always needed.

The third key is that you’re teaching them.

No matter how advanced a developer is, they’re reading your documentation to learn from you. You don’t have to know everything about programming. You just have to explain one parameter. And for that, you may have the full support of your company and your development team. You need to give the readers the information bluntly, quickly, and effectively.

In the meantime, read my Robert’s 33 Rules of Order for API Documentation Writing. These are 39 rules (I added some more after I first published it, but I thought the original was a catchy title) that summarize everything needed to write API documentation.

This short discussion can’t cover the entire topic. So, I’ll abbreviate key points. The following are the three most important skills in this trade.

Master the One-Sentence Description

Learn to think in one-sentence descriptions. Begin the first sentence of every parameter, property, or request with a short, sweet one-sentence description. “This parameter does X.” No details, no embellishment, no specifics. Just one sentence. Master this approach. Make it second nature.

Here’s the status quo way. Readers may not understand what this does at first glance. Neither does it help that it’s poorly written.

Here’s a better example. The one-sentence description sets the context upfront. Knowing that, everything else becomes a detail.

This does two things. First, if you can summarize a concept in one sentence, you’ve learned that topic. This implies that you have to learn the topic first, before writing about it. Only then can you summarize. This also means if you can’t summarize it in one sentence, you don’t know the topic. It’s an objective way to test yourself if you know your stuff. If you don’t, go back and learn it.

The second thing is that it saves the developer time. In a single sentence, they get enough information to know if this is what they’re looking for. If it’s not, they move on. They will love you for saving them time. If it is what they’re looking for, they can keep reading.

You can include additional details in subsequent sentences. What would the second more important fact be about the parameter? And so on.

Make Calls in Postman

Learn Postman. This may be the single most important tool we have. Postman is an application for all things API development. Developers can use it to create APIs and even generate the code for them. It can be used to write or generate documentation. Testing becomes a requirement. API documentation writers need to test every request they document. That last sentence is worth re-reading. It can’t be any other way. This is how we learn the requests, the parameters, the properties, and the nuances of the request. We’re also testers. Force errors in the request, such as omitted parameters or passing a numeric value when an alphabetic one is expected. We learn as much from the request failures as we do from their successes.

Interviews? Practice, Practice, Practice

You never get proficient without practice. And lots of it. Getting a job is no different. But this isn’t taught. Schools and colleges don’t stress it. Perhaps as the most important part of a job search, are we expected to just wing interviews after four years of preparing our skills? Of course not. It’s foolish to think that. That foolishness ends here, too. As far as interviews go, get as many interviews as possible and see them all as practice. Only then will you be ready for the one interview that counts. That means applying to every place you can. There are plenty of job-finding sites. LinkedIn is the site du jour. In the Jobs tab, search for the positions you’re even remotely interested in.

You have to get the attention of the recruiters first. Get your resume buffed up, and get your LinkedIn profile lean and mean. They’re going to look at your profile. Not only count on it, but also make it an extension of your resume. Consider both your resume and profile to be living documents, and change something in both of them at least once a week. Change it based on what you learn from interviews.

In addition to formally applying through their website, sneak past the front door. Have someone from inside the company turn your resume in for you. That’s easiest done if you’re lucky enough to know someone inside the company already. If you don’t know someone, pick someone. It doesn’t matter if they’re a LinkedIn second-level acquaintance or someone you picked at random. It’s best if they’re a fellow writer. Be prepared for them not to help you. It’s part of this game and you can’t control that. Just pick another person and move on. The important thing is to get the interview.

It doesn’t even matter if you think you’re not qualified. Job descriptions are so poorly written, you’re safe to ignore many of their so-called requirements. If something is important to them, they’ll ask during the interview. The point is to practice interviews.

• Get familiar with the types of questions they’ll ask. The initial interviews are with recruiters screening applicants. They tend to ask similar questions.
• Prepare your answers. Nothing turns a recruiter off more than long pauses before answering, long meandering answers, or starting an answer with the classic umm. Judge Judy is right when she says “Umm is not an answer.”
• Get comfortable with the question-and-answer format. You want to get to the point where you can answer quickly, clearly, and with enough detail to show that you know what you’re talking about.

But all this takes practice, which is to say, repetition. Why would it be any other way? Remember, you’re trying to essentially get thousands of dollars from this company. Why would anyone expect to be good at something without practicing?

One important point is to ask questions back. A key point is when you’re asked if you have any other questions, tell them you do but you have technical questions and you’re looking forward to speaking with the manager or another writer. This is not patronizing to the recruiter. The recruiter is not a technician, and even if they are assigned to a writing department, they themselves are not technical.

Resume Tips

Writing a good resume is a topic I’m not going to cover here. Certainly, there are many opinions about what makes a good resume. But there are two things I like seeing.

Grab Their Attention

Technical writing isn’t exciting to read, so make it exciting. Add a section called Summary. Don’t go conventional and say things like:

· I’m highly organized and innovative.

· Collaborative, detail-oriented Technical Writer with 3+ years of experience authoring high-quality software documentation, templates and user guides/manuals to clearly and efficiently explain highly complex systems and processes.

Ugh. Those statements mean nothing. Of course, everyone likes to think of themselves as “highly organized and innovative.” The second one’s a long run-on sentence with so many buzzwords that it contradicts their authoring high-quality documentation. Remember, for technical writers more than anyone else, the resume is a writing example. As a reader of this resume, why wouldn’t I think that their documentation would be just long, ineffective sentences?

Instead, say what you do in very overgeneralized ways to get their attention. For example:

· I make API documentation to be the single source of truth for developers.

· I translate what developers do into plain English.

· I quickly become the subject matter expert who people come to first.

Keeping true to John Lienhard’s Principles of Minimum and Maximum Drama, since we all understand this about technical writing, the truest explanation is the one with the greatest dramatic content.

Support Your Statements

Now you have the recruiter’s attention and can use the rest of the resume to support that. Just don’t only tell things you’ve done in the past. Recruiters don’t actually care. For example:

· Completed weekly TPS reports.

That statement is so boring that I had trouble just writing it. No one knows what a TPS report is, what it takes to complete it, or who reads it, if anyone. Instead, since something goes into TPS reports, tell them. Something like you wrote summaries of developer project deadlines, calculated the number of new users, or such.

Next

Next up is getting yourself noticed. There’s more to you than just that resume. There are also other ways to get to the recruiter. Remember, we’re trying to stack the odds as much in our favor as possible.