Keep the marketing department out of technical documentation

Why marketing should make the user manuals! is a very interesting post that makes the argument that the marketing department should play a role in creating user manuals.

Now the title is a little misleading. The author isn’t actually making the argument that the marketing department should be making the manuals. They’re just saying that all the talent in the marketing department should be used to create great user manuals.

As a technical writer, I’m not certain that this argument will hold. There are a few reasons for this.

The brochure is short. The manual is long.

All the wonderful beautiful paper used for glossy promotional material doesn’t come cheap. It’s cost-effective to attract new users with an expensive four-page brochure. It’s not cost-effective to print a huge number of manuals with the same high quality. Four-page glossy versus 100-page glossy.

Documentation isn’t important.

Documentation gets the short end of the stick in pretty much any industry I’ve ever worked in. It is “not a priority” because it doesn’t do anything to sell the product. It is not a “feature” that will move more products off the shelves. A nice manual is good but, in the minds of product development, not really necessary. They’ve got the product, why kill themselves with a good-looking manual?

There are too many stakeholders in the documentation. AKA Bob in Ohio knows what needs to be in the documentation.

Repeat after me: Documentation doesn’t matter except when it does. This is a constant struggle in documentation departments. Supposedly nobody cares about the documentation so we’ll try to pare it down to its bare essentials so that the user can access the information they need quickly and easily. An engineer, product manager, or software developer will step in and say, “Well, I talked to this guy named Bob in Ohio and he says he’d really like to understand more about the F-stop functionality on the S5000 camera so we better put it in.” So the documentation department is stuck adding an extra chapter about F-stops because Bob in Ohio mentioned in passing that he’d like to see that in the manual.

How does this relate to glossy documentation? Easy. Every hour we spend documenting unnecessary information is one less hour we can spend on creating effective documentation.

Technical writing is not copywriting

There is a widespread assumption that tech writing is just writing. You know, it’s like an essay. Anyone can write a manual. After many years of suffering through truly bad technical documentation it has become crystal clear to me that good technical documentation is not something just anyone can whip up. It is an entirely independent field that requires a serious amount of skill and learning to execute properly. I am certain that a significant amount of technical documentation is created by people that are not trained as technical writers or are just plain bad technical writers. And this is the main reason that technical documentation generally sucks across the board. Asking the marketing department to do the job will create prettier documentation but it will not create better documentation.

Technical writers need to be exposed to things beyond writing

Most tech writing courses are geared to writing. Makes sense. But most technical documentation is ugly and inefficient because tech writers don’t have a clue about good design. Aesthetic appeal is not considered a mandatory part of technical documentation. This is a shame and one of the main reasons that technical documentation is generally ugly. I mess around with print and web design so I have at least some idea of what makes up good design. The vast majority of technical writers just don’t do design. The result is ugly documentation.

The solution would be to involve designers from the marketing department in the documentation process but there are limitations…

Technical writing tools are not design tools

Making a glossy brochure in InDesign is easy. Making a glossy technical manual in InDesign is a bloody pain in the goddamn ass. InDesign has some functionality that deals with chapters and numbering but InDesign is a layout application. For proper pagination, numbering, indexing, TOC generation, headers, footers, and all the rest, you need a tool like FrameMaker, AuthorIT, or LaTeX. These tools are not layout tools. They are long-document management tools. It’s not impossible to make a good-looking manual with these tools but it is much harder than it appears. So you have choice: Make a sexy manual that’s a goddamn pain in the ass to maintain because your numbering, pagination, TOC, and indexes are FUBAR on a regular basis or create an ugly manual that’s easy to maintain.

Again, it’s possible to have both. Especially if the documentation isn’t too long. But making an attractive long document is going to cost. Which comes back to money. Most companies don’t spend money on technical documentation.

Involving the marketing department is a nice idea but until the marketing department understands what makes up good technical documentation, technical writers understand good design, Bob from Ohio steps out of the picture, effective layout software that handles long documents comes into existence, and companies actually spend the dollars to make the user’s life easier, we’re stuck with less than stellar documentation. And involvement from the marketing department would cause way more problems that it solved.

posted at - 8:34 pm - 9/7/2006

frequent visits...


in here...

web goodness...


supporting roles...