« Top of the housing bubble perhaps | Main | Webcam on Ubuntu, part V »

February 27, 2006

Tech documentation fundamentals

Bob DuCharme has written a succint description of the documentation you'll need for your next product. In a very small nutshell, you answer Bob's questions:

How do I get up and running with this product? How do I make the product do this particular task? What will that aspect of the product do for me?

He's right that the hard part is answering the middle question. Most of the software I've doc'd is aimed at people who build and manage systems. Often the list of tasks you have in the beginning is oriented more towards problems the product creates for the user -- things you have to do to get the product to do anything at all or at least anything interesting; things you know how to explain -- rather than problems the user had in the first place, the problems that brought the user to your product.

The real value we can provide then is in understanding real tasks a user's trying to accomplish, and showing how to do those. Are we writing the task-related docs too early? Perhaps in many cases we should plan for the User's Guide part to grow only after we've finally understood what users are trying to do.

Posted by Mark at February 27, 2006 06:30 PM

Trackback Pings

TrackBack URL for this entry: