Short-sighted seduction: Tech comm as a task

Treating tech comm as a task, not a profession, is seductive, but harmful.

This is the story of how a seemingly sensible management decision about documentation has inflicted avoidable damage on a product. Read how the idea that “anybody can write” can backfire.

Best intentions

Imagine a software company. They decide to revamp one of their products. It’s gotten a little long in the tooth and deserves a renovation. Requirements and designs are written, modules are developed and tested. Documentation was previously understaffed, but that wasn’t a severe problem.

The shipment date approaches, and things get a little tight: Usability and performance tests lead to additional developments which lead to more tests. The flexible corporate culture pays off as they assign developers and testers from other units to revamping tasks. Meanwhile, documentation takes a backseat: Compared to development and test, it is less important for shipment, hence it is less urgent and gets less attention.

Original sin

Then the lone writer speaks up: He cannot keep up with more developers who keep changing the product at a more rapid pace. His manager has to watch the budget and cannot take on more people. So he does the most sensible thing. He breaks documentation into several tasks and assigns them to whoever has time and knowledge. After all, how hard can it be…?

So developers write online help. They build the windows and can explain how they work. Testers write the release notes. They test the changes and new features and can describe them. The lone writer writes the user manual and coordinates the other writing tasks.

And they launch on time, barely so, with a few glitches, but – phew.

Merrily chugging along

Fast forward, one year later. They develop version 2 of the revamped product. The lone writer has left. A tester will coordinate the documentation efforts. After all, how hard can it be…?

The online help and the release notes come off as before. No one has time to update the user manual, so they postpone it. From the manager’s perspective, documentation as a task works and makes it easier to distribute all tasks among all developers and testers.

Too late

One more year later, there are problems: After shipping version 2, customers started complaining that the documentation was incoherent. Some online help is more helpful than other entries. The release notes describe features that are neither in the online help nor in the manual. The documentation in general is now seen as a burden and a competitive disadvantage.

A business consultant takes a close look at the documentation and finds the complaints are justified. Much documentation focuses on features and reference information. Customers ask for workflows how to set up and operate the product, which is described in the outdated manual.

Lesson learned

As far as technical communication is concerned, I think there is a single simple lesson here: High-quality documentation requires a professional who is responsible and accountable, just as in development or test.

There are two reasons which I think managers should understand:

  • To write effective documentation which can be maintained efficiently and used effectively requires experience and standards. To assign documentation as individual tasks creates incoherent, unmaintainable documentation with overlaps and gaps.
  • As in development and test, what is seductive and cheaper in the short run, costs more money in the long run.