Keep marketing away from the documentation

Marketing and technical writing. They’re at two ends of a spectrum. As a former co-worker once said “We deal with facts. Marketing deals in hype.” That might seem a bit extreme, but that’s the way it sometimes feels.

But in some circles, there’s a feeling that marketing should be involved in the creation of user manuals. I’ve heard a number of people, notably Kathy Sierra, argue that marketing should play an integral role in the the documentation process.

Darren Barefoot (with whom Aaron and I will be appearing on a DocTrain panel in May), on the other hand, disagrees. This older post explains at length why documentation should be kept out of the hands of the marketing department.

Darren makes one really solid point:

The user has already bought the product. They want to know how it works, not why it’s good. Often the people using the product are not the people who bought it. They don’t care why it’s good. They just want to know how (not why) it will make their lives easier.

In a few instances in my experience, the documentation that I’ve worked on has been used as part of marketing and sales efforts. The folks involved in pushing the software didn’t have a hand in writing the docs, but they did use the manuals and help to do what Darren mentioned: show potential customers what the application can do. In a couple of cases, the documentation played a small role in making the sale.

It shouldn’t be us versus them

In the various development shops in which I’ve worked over the years, I noticed polarized attitudes towards users. In couple of the shops, developers really went out of their way to address the needs of the users. They listened to the concerns of their users, tried to give them the features that they wanted, and fix usability problems with the application. They didn’t always succeed, but many of the customers appreciated the effort.

Continue reading

Fostering user and author collaboration

As was discussed in a previous post, users can be an excellent source of information and of documentation. One of the key problems is how to get the community of users involved.

This article looks at the problem from the perspective of educating new users. The author points out:

… the value in educational content lies in context (what immediate problem the reader is trying to solve) and timeliness (what’s true today will be outdated tomorrow). Value no longer lies in the traits associated organization, pace, and tone as in traditional books.

Musings on user-generated documentation

User-generated documentation is a big issue in technical communication circles. Aaron and I have discussed this topic on and off over the last couple of years, but really haven’t come to a definitive conclusion on the merits of user-generated documentation.

However, this post at Craig Haiss’ Helpscribe blog got me thinking once again about taking advantage of the knowledge of users. If properly done, tapping into the knowledge of users can improve the quality and breadth of your documentation.

Continue reading

Developing documentation, the FLOSS way

I enjoy reading about the processes used by other technical communicators and those working on various types of projects. Not everyone will tackle a project in the same way, and there’s often something to learn (or at least to get me thinking) by studying someone else’s approach.

While the Free/Libre/Open Source (FLOSS) community is sometimes seen as a bunch of unguided missiles heading towards the same target, it’s actually more structured than that. This guide, from the Fedora Project, is a detailed look at one approach a FLOSS project uses to develop documentation.

Baselining documentation on a wiki

Like them or not, wikis are becoming more and more common in various enterprises. And they’re not just a developer’s tool anymore. They’re used fairly extensively for documentation, too. The beauty of wikis is that they’re easy to use and that they’re living documents. The content on a wiki is constantly being updated and (you hope) refined.

The dynamic nature of wikis, though, can cause a few headaches when you need to baseline documentation that’s on a wiki to correspond with the release of your product. That’s the problem that we ran into at the firm at which I’m working right now.

Continue reading