How to write documentation

[Roy Smith]

> In article <6452 at utzoo.UUCP>, henry at utzoo.UUCP (Henry Spencer) writes:
> That "verbiage" that is so opaque often consists of passive constructions
> which totally obscure the point to be made. [...]  This type of
> construction is depressingly prevalent in documentation of all kinds on
> all systems.  It should be taken out and shot.

	The following book is absolute must reading for anybody attempting
to do any technical writing:

%A R. A. Day
%D 1979
%T How to write and publish a scientific paper
%I ISI Press
%C Philadelphia, Pa

	It's a short (150 page?) paperback, chock full of examples of how
you shouldn't write.  The author used to be the managing editor for a major
scientific journal, and has collected over the years a huge collection of
examples of horrible writing.  The book is informative, easy to read, and
quite amusing.  If you are writing documentation and havn't read this book,
stop what you are doing and go buy it!

	Notice in the last sentence, it's not clear if I meant to buy the
book or buy the documentation.  This is the sort of stuff the book teaches
you to watch out for.  I meant the former.
-- 
Roy Smith, {allegra,philabs}!phri!roy
System Administrator, Public Health Research Institute
455 First Avenue, New York, NY 10016