documenting error messages

[Susan Fowler <sfowler -at- EJV -dot- COM>]

Re. Sara Mutton's suggestion, "You also might start collecting material on how
 to write error messages and GUIs and dropping them conspiciously on the
 keyboards of developers when they are away from their desks."

The GUI Style Guide has an entire chapter on writing messages--error, notes,
 hazard, audio, what have you. The book as a whole is designed to help companies
 make their GUIs more professional.

Let me back up a step: Victor Stanwick and I (both of us tech. communicators)
 wrote the book for exactly the situations described in this thread. We were
 both sick to death of fixing the interface in the documentation. We wanted to
 help make it possible for fellow tech communicators to fix the interface
 directly, either hands-on using the various GUI development systems or by
 educating the developers.

Developers, by the way, are often so busy writing the code that runs the
 underlying processes that they are happy to hand off the interface design to
 human factors people and writers--provided that we sound like we know what
 we're doing. (Some authors say that interface development takes up 50-60% of
 development time. This seems high to me--as if there are no screen painters and
 the developers have to create buttons and menus from scratch. Anyone have other
 ideas?)

It may be that taking on window development is impossible within set deadlines
 and budgets. On the other hand, spending time to create an easily documented
 interface may be more time- and cost-effective than struggling with the
 hard-to-document interface.....

Hope this helps.

--Susan Fowler
co-author, The GUI Style Guide
Academic Press Professional, 1995
ISBN 0-12-263590-6