The "Tell them once up front" style

[Arthur Comings <atc -at- CORTE-MADERA -dot- GEOQUEST -dot- SLB -dot- COM>]

> One of the basic tenets of tech writing is write the book for your
> audience. Your audience may want a reference guide that is not read
> cover to cover. Your audience may want a getting started guide that is
> read cover to cover - like a novel. Tech Writing does not define
> the style or organization of your book or online help. Your audience
> does.
> Jim


Sure, but you don't have the luxury of starting from scratch to develop
a new set of conventions for each audience.  That's why we share (or
study in school) principles that have worked for quite a few situations
in the past.  No one's suggesting that you follow them slavishly.

I submit that very few people read technical documentation like they do
novels, and that -- regardless of what you would like to think --
almost no one reads it cover to cover.  I have heard that such people
exist, but nothing I have ever seen has convinced me that they're very
numerous.  I wish they were -- I'd love to be able to write in the
"Tell them once up front and it's their fault if they don't remember"
documentation style, but I think that's for our convenience, and
doesn't let readers define how they actually interact with manuals.



Arthur Comings

GeoQuest
Corte Madera, California
atc -at- corte-madera -dot- geoquest -dot- slb -dot- com