Stories
Slash Boxes
Comments
NOTE: use Perl; is on undef hiatus. You can read content, but you can't post it. More info will be forthcoming forthcomingly.

All the Perl that's Practical to Extract and Report

use Perl Log In

Log In

[ Create a new account ]

TorgoX (1933)

TorgoX
  sburkeNO@SPAMcpan.org
http://search.cpan.org/~sburke/

"Il est beau comme la retractilité des serres des oiseaux rapaces [...] et surtout, comme la rencontre fortuite sur une table de dissection d'une machine à coudre et d'un parapluie !" -- Lautréamont

Journal of TorgoX (1933)

Saturday June 15, 2002
02:38 PM

Writing

[ #5684 ]
Dear Log,

A friend and I were pondering why it's hard to write content for tech books. At one point I said:

And maybe people assume that since they can write (supposedly) clear documentation, that they should be able to turn right around and write a tech book. I think that writing documentation teaches some very bad habits -- it kills whatever meager ability people have for thinking about who the audience is, because it seems that in writing documentation, it's (dismally) conventional to assume that the reader already knows everything you do, except for the exact parameters for the function/method being discussed. But in a tech book, it's vital to think about what the reader might not already know. Ergo: don't write an explanation of HTTP that uses the term "TCP stack", because the average reader who doesn't know what HTTP is, doesn't know that a TCP stack is either.

The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.
 Full
 Abbreviated
 Hidden
More | Login | Reply
Loading... please wait.