Reading API Documentation Writer’s Job Descriptions

7 min readJan 4, 2025

By Robert Delwood, A Lead API Documentation Writer

The quality of job descriptions varies wildly. That means how the job is described, the components of the job, and expertise expected for each component. The descriptions are better for the common job types, such as project and product managers, developers, and sales. Companies know what those are and have experience hiring those.

All that falls apart when it comes to writing, of any type, and specifically API documentation writers. CEOs, who I love to vilify for this reason, generally don’t understand technical writing and technical writers. To them, and that attitude often trickles down the table of organization, see copy, marketing, content, and technical writing as the same and interchangeable. I believe this causes the low pay rates, because we’re seen as a commodity, going at market rate. A doctor with 15 years of experience is treated as an expert. A writer with 15 years of experience competes in the marketplace with junior writers. A shame for sure. I digress some but that needed to be pointed out.

There is information to be mined from bad job descriptions, if you know what to look for and know how to use that information.

Red Flags

It gets worse with API documentation writers. Fewer CEOs know what we do, much less that we even exist. This can be seen in job descriptions as a series of red flags.

The Role Title

The first red flag is that the position titles commonly are Technical Writer or API Technical Writer. Both titles understate the position, expertise, and experience. This is not a criticism of technical writers. It’s criticism of how companies value the API documents. A more informed and precise title would indicate the company’s greater value and awareness of the role. For example, a good title is API documentation writer.

The Job Description

The second red flag is the job description itself. The following is typical.

Notice that the API documentation portion mention is last. The excessive capitalization aside, this is not always so but rarely is it ever first and more rarely is it the only mention. In any case, it projects this role as incidental or as an afterthought.

This vague reference may indicate a lack of commitment by the company. Here, this is seen as the expectation of the writer also creating divergent documents such as user guides, technical reference guides, release notes, technical and security bulletins. These alone would press any technical writer much less also expecting API guides. This probably underscores the company isn’t investing in the API documentation writer specialty role. The fact should also bother technical writers, too. The company sees all writers as commodities and interchangeable.

It may also indicate a lack of understanding of the API documentation role. The company may not aware of this specialty. API documentation is seen as one of many documents that any writer can produce. The truth is API documentation is a full-time commitment and a specialty. The company gets out of it what they put in to it. In this case, the company is investing to make their client base, that is, the people who pay them money, to make their jobs easier. To be successful, that means investing in writing skills, experience, and specialties. How can companies not see this?

The Qualifications

The third red flag is the qualifications they list. The qualifications should be consistent with the job. Too, often, qualifications are either vague (“Create high quality documentation,” “translate complex technical information into clear documentation”), inappropriate (“Must be familiar with Madcap Flare, Confluence, and Microsoft Office,” because those tools are not commonly considered API documentation tools), or inconsistent with the task. For example, here are two common terms to watch out for:

Madcap Flare. This is a great tool, but not for API documentation. If the company lists this, they don’t know about other relevant tools like Microsoft Visual Code or static generators. Else they would have said so.

Swagger. This is an obsolete term and should never be used to refer to the contents of API documentation. Swagger, the original tag-oriented API documentation language was donated as OpenAPI in 2016 and discontinued as a platform in 2017 with its version 2.0. I don’t know why people still use the term Swagger. People who don’t even know what it is or what we do call it Swagger. Swagger still exists as a product. SmartBear has a tool suite called Swagger. The most used of those tools is the Swagger UI and editor. Keep in mind it’s a trademarked tool suite. Terms should be used precisely and this is no exception. The file content is not Swagger. In general, don’t use this term. You probably mean OpenAPI.

SMEs

A fourth red flag is the dependence on SMEs (subject matter experts). The job description may say the writer will interview SMEs or transform SME information into detailed documentation. Statements like this suggest that the company doesn’t expect the API documentation writer to be skilled enough to write their own material. The company doesn’t know what we do. The truth is, the writer is a peer of developers and must work independently. Writers need to understand developer’s processes and code. We’re here to take work off of developers, not to increase it.

Talking to developers is important, yes. But to supplement the information, not the be the source of it. For that, writers have specs, Postman, and experimentation. The best companies expect writers to know the API so well that writers can answer client’s questions. You don’t get there by having developers tell you everything.

The Existing API documentation

The potential fifth red flag is to look at the companies’ API documentation. Many post these publicly. The quality of the documentation is going to be the quality of the management and writer who created them. It doesn’t mean they are bad managers or technical writers. It may mean they’re bad, inexperienced, or untrained at writing API documentation. It’s a specialty, so why would it be any way else?

Spotting these are easy, too:

Fields don’t have descriptions.
Fields have one line field descriptions. Rarely can anything be described in a single line.
There are no or few examples. Keep in mind, developers get more use and information from the examples than they ever will from the text. If nothing else, think copy and paste for developers.
Valid values are not listed.
Examples in the body are nothing more than string or null
The grammar is unacceptable. Sentences aren’t complete, don’t have periods, or acronyms are not defined or capitalized. The irony is that the same errors in an applicant’s resume gets judged more severely than if they appeared in the API documentation for paying clients.
Required body parameters are not marked.

The list goes on. These are unacceptable for client developers. It’d be like assembling Ikea furniture with wrong instructions. Just because they could do it doesn’t mean you’ve done the right thing or that’s the experience you want them to have.

What Do These Mean To You?

By all means, still apply to these companies. But you’d be going in with more information than they think. An implication of having too many red flags can indicate several conditions:

They don’t have any technical writers, at least not assigned to API documentation.
They don’t have any dedicated API documentation writers.
They don’t have a writing department or a writing manager.
Developers are writing the documentation. If you wanted to press your advantage in an interview, this is the easier pressure point to use. Developers don’t want to write documentation, they’re not good at it, or they’re not trained at it. They want to write code and documentation is a distraction to them.

If a company has several of these red flags, the takeaway for you is that you can lead the conversation more. Don’t do this with the screener, you have to get past them first. When you talk with the hiring manager, you can take the initiative. At the least, you can be more confident in your answers and suggest actions. In the case of not having a writing manager, they would be looking to you for leadership. The interview is a good place to show that. Those starting out in this profession know that there’s a fine line between confidence and arrogance, so this may take practice. Those with experience and already have interview experience, know where that line is. The point is, you’re going in with information that other candidates don’t have. That can be a powerful advantage.

A Good Example

The following is a good example of an API documentation writer job description. The job title, not shown here, is API Technical writer. But besides APIs, there is no other document mentioned. The qualifications are consistent with being an API documentation writer and are also all reasonable. None waste our time or makes the company sound unknowledgeable like “ability to work autonomously,” “be proactive,” or “function in a productive team.” I have every reason to believe this company knows what writing API documentation is, has done it before, and can manage that task. In fact, I think the hiring manager wrote this description, and not HR, because of the precise terms and correct usage. This would be a good company to work for.