Words on a page

This is one of the main rules of writing documentation. But you'd be surprised at how many people don't follow this rule. Take the large company I worked for a couple of years ago. Their documentation was wordy beyond belief. Why? The editors deemed it necessary to explain everything in detail to the reader.

The head of documentation and training freely admitted "we (the doc teams at head office) don't know who our audience is." The problem, though, was that the team I worked with in Toronto did know its audience. And knew it well. Most of what we were forced to do didn't please that audience too much.

Like what, you ask? Well, the editors insisted on having us include a business reason for every task. Including how to start the application from the UNIX command line. I explained to the editor (quite pointedly) that the "business reason" in this case is to be able to run and use the application. I then told him that our users were reasonably intelligent people. They implicitly understood this. They also knew that they had to turn their computers on in order to work with them, and could actually do that by themselves.

I'm glad I don't work for them anymore ...