Overview of the writing process
If there’s one topic in this course that is glossed over, it’s the writing process itself. This is ironic because, more than anything else, it’s the content that matters. And this content is likely your primary stewardship.
If you’re an engineer, the task of writing might be unfamiliar territory and the blank page intimidating. You’re likely burdened by the curse of knowledge, unaware of what jargon might be familiar or unfamiliar, unsure of the assumptions about the user’s setup and knowledge. The blank page might give you writer’s block.
On the flip side, if you’re coming from a humanities background, you might be intimidated by all the programming-specific terminology and concepts, unaware of the technical level and familiarity of the users, unsure of how things work on a code level, confused about what to call various elements, and more.
So whether you’re an engineer or a professional writer, writing API documentation can be tough. It is extremely challenging, and most of the how-to texts on writing give you very plain, bare-bones writing instruction.
For example, most texts will explain that you first need to understand your audience’s needs, gather your sources, write an outline, draft some content, review and edit the content, and finally publish. These are the phases of the writing process, but these general descriptions don’t tailor the tasks specifically to the tech writer’s scenario nor give you insider tips on how to succeed.
Rather than rehash the same writing steps and phases, I’ll instead paint more of an inside, hands-on guide to the documentation writing process, with the most practical tips I can give, specifically tailored to technical writers creating documentation.
The writing process involves these five general steps:
Entire books could be written about each of these phases. I tried to pick out a few salient tips and practical advice for each section. But by no means is my advice comprehensive. If you’re a seasoned pro, I invite you to add your own tips and insights in the comments for each page.
The writing scenario
Before we jump into this process, let’s start by presenting a writing scenario. A product team (consisting of a handful of engineers plus a product manager and QA) is creating a new API. In contrast to the more language-agnostic territory of REST APIs, this happens to be a Java API. Your target audience involves engineers who know Java and, for the sake of having a concrete use case, they are implementing the API to pull location data about coffee shops. They’re using the API to allow coffee vendors to build map-based Android apps that identify which coffee shops in the city sell their brand of coffee.
The API is slated for release next month, so even though engineers have been cracking away at this API for half a year, they’re mostly done and ready for you to create the documentation. You have about three weeks to learn the product, write the docs, get the docs reviewed, and publish the docs in time for release.
This is a very typical scenario and timeline, by the way — being brought at the last minute, often unaware of the product’s development cycles that have been going on for months previously. Product teams are long past the stage where they debated the best implementation, the feature set, how the API matches use cases, and so on. By the time you’re brought in, they’ve already entered QA testing stages and just need to put a bow on the product with some docs before shipping it.
Next steps
Continue on to 1. Planning.
About Tom Johnson
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.
89/166 pages complete. Only 77 more pages to go.