Search results

A Reverse Approach to Help Authoring: Writing Documentation Post-Release

by Tom Johnson on Feb 2, 2012
categories: technical-writing writing

When I first started as a technical writer, a senior writer taught me how to write documentation. Her approach, which aligns with the traditional way of doing technical writing, generally followed these steps:

  1. Get involved as early as you can in the software development process. As soon as prototypes are available, or a functioning development environment, start the documentation process.
  2. Think of all the main tasks users will do with the application. Make a list of the tasks and begin documenting them in careful detail.
  3. As the application nears release, finalize your help material so that it's ready when the application launches.
  4. Once the application launches, move on to another project.

This traditional method of writing documentation places all the work before release. Sometimes I think the bulk of documentation should be written after release. This "reverse method" aligns more with support center philosophy. Some support centers believe you shouldn't write anything until a user asks a question. Only then do you begin to document answers.

The Reverse Approach to Documentation
With a reverse approach to documentation, you place more emphasis on the help material after the release rather than before.

But you might object and say that our job is to anticipate the user's questions and pain points so that when they do search the help file, the answers are there waiting. This in fact is Ginny Redish's premise in Letting Go of the Words. She encourages us to imagine a conversation with the user, anticipating their questions and responding as if in conversation.

I think imagination, even user interviews, are good techniques. However, too often I skip over this. I end up giving nearly every topic equal attention, documenting with careful detail both the obvious tasks and the difficult tasks. My imagination is usually an extension of the product manager's vision and understanding, which I inherit from dozens of project meetings. The closer and more involved I get into a project, the less clearly do I see all the assumptions I'm making, the workflows I'm immune to, how blind I've become. No one can predict the future. How often have our anticipations and imaginations perfectly matched user reality? Do we even know the user's reality?

With the traditional method of documentation, after the application is released, I'm not as closely involved with the project anymore. I don't have my nose in JIRA; I'm not carefully monitoring all the incoming feedback. In my mind, I'm done. User pain points and frustrations often go unnoticed, while my attention shifts to new projects. I may add a topic here and there, or add some more detail, but by and large, documentation is mostly done when the application is released. I think that's a harmful mentality that might be cured by a more reverse approach.

Let's rethink the model. With a post-release documentation emphasis, the technical writer pays careful attention to every incoming question, comment, and feedback item from users. Whether through support center calls, forum questions, feedback emails, webinars, or other channels, the technical writer carefully monitors each question and begins building the help material from these questions. User feedback drives and shapes and structures the help material. It determines what we write, how much emphasis topics receive, and how visible we make those topics.

Now I'm not an extremist. I know that some help material is necessary when an application is launched. Quick reference guides and some basic help material would probably suffice. It would give something to the user to get started and not feel alone or abandoned. In some cases, a short series of video tutorials might also be helpful. After all, users need the most help when the application is newest to them, that is, when it's first released. Abandoning the user in their time of greatest need may seem somewhat cruel and unproductive. I'm not saying no documentation should be written prior to release.

And yet, the long help file can wait. Wouldn't we be much better to start writing help in an intensive, 100% heads-down manner during alpha and beta testing periods, and then during the first month of release? After all, how much time do we waste trying to figure out how a partially-built, bug-ridden application works in an unstable development environment? Wouldn't our time be better spent waiting for the application to reach a near-production level, and then once that level is reached, focus all our energy on creating help material for it, based on questions and issues and frustrations users are experiencing?

Without a launch date for an application, there's no clear date when documentation is done. In this post-release, reverse model, documentation can keep growing as long as users continue to ask questions and experience frustrations. Documentation is probably finished when the incoming feedback dies down, when most of the incoming questions can be answered with simple links to answers in the help.

Feb 3 update:

Check out this video from Greg DeVore that expands on some of the points I make in this post:

For a contrasting perspective on the idea of reverse documentation, see this post by Kristi Leach, When is it time to hire the technical writer?

About Tom Johnson

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.