Reading API Documentation Writer’s Job Descriptions

Yogi Berra was right: You can observe a lot by just watching.

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.

Marketing

The job falls under the marketing department. Developers hate marketers. They make fun of them and marketing speech relentlessly and unmercifully. If the job is listed in the marketing department, it’s safe to assume there is no formal technical writing department and technical writing manager. This means you can consider taking a more decisive tone with them. You can lead them to your points and almost dictate ideas to them as if you had the job. There’s a fine line of course, but the decisive tone is good.

The Job Description

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

Notice where the API documentation is mentioned. In one case, it’s just one among others, and the second is last. In any case, it projects this role as incidental or as an afterthought. This indicates the company sees API documentation as just another form of technical writing. It’s not. It’s its own specialty.

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.

Skills examples include “Familiarity with writing content in Markdown,” Git, GitHub), like branching, forking, and resolving merge conflicts, using PR-based workflows, Experience with Linux and working from the command line, collaborating cross-functionally to gather technical information, Experience working remotely or collaborating from an office with remote teams. None of these are job requirements. They’re skills. Skills they can learn along the way. The company’s going to teach you these regardless. They have nothing to do with being a good writer.

The they get into softer skills like “strong research skills, “the ability to pick up new technical concepts quickly,” or a “well-developed reader empathy.” These aren’t even provable. No candidate in their right mind would deny any of these. So why include the mention at all? In fact, notice, none of these have anything to do with writing.

Finally, they put the most important skills as “nice to have” and at the bottom, like “familiarity with OpenAPI (Swagger) specs and API docs.”

Clearly, whoever wrote this either 1) doesn’t know anything about what writers do, which means an HR person and not a writer added this, 2) the hiring manager themself is not a writer, or 3) they want to sound official and professional by throwing in a lot of buzz words. In any case, these are red flags.

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.