Well, This Is What We’ve Been Saying For Years

TechRepublic recently posted an article titled, 10 ways developers can meet user expectations and ease frustrations. The list included things like accurate data, responsive user interfaces, compatibility, responsible resource consumption, and others. Being a technical writer, #7—Documentation, naturally caught my attention:

We all know how much developers dislike writing documentation. So we tell ourselves that the application is so easy to use, “only an idiot would need a manual.” There are two problems with this thinking. The first is that the world has plenty of idiots in it. The second is that we are usually wrong about how easy the application is to use. If your organization has a technical writer to create the documentation, involve that person from the get-go; the top complaint I hear from technical writers is that they are handed a nearly finished product and told to document it, with little insight into how it actually should be used. If you do not have a technical writer available, you will really need to work hard to make sure that the documentation does not merely state the obvious and is written in a way that will be helpful to end users who are unfamiliar with your application.

I’ve been at this for more than a decade and it mystifies me that this point STILL has to be drummed into the heads of managers and development teams. Or that #10 on TechRepublic’s list—Does what it says it will—has to be either. With all the blogs out there that crucify products that are anything but user-friendly, and with help desk call databases documenting the “how do I….?” calls that come in over and over again, it shouldn’t be such an epiphany that users have no patience for products that

  • don’t deliver on the promises made during sales pitches
  • are not intuitive to use
  • don’t have even the the most basic of documentation

So, instead of burying this discussion on our SIG listserv or the Discussion Board of our LinkedIn Group, let’s get it out in the open for everyone to read. What’s the reason—or reasons—for this persistent block? What’s the “magical sales pitch” that you, fellow tech writers, think will help clear the blocks once and for all?


One comment

  1. LeRoy O'Bryan

    Is it possible that tech writers need to seek out projects within their company versus hoping company management will find out sooner or later that they are there and then give the tech writer a project?