Re: Chapter Numbering

Subject: Re: Chapter Numbering
From: Stuart Burnfield <slb -at- FS -dot- COM -dot- AU>
Date: Wed, 15 Oct 1997 16:51:57 +0800

This, slightly paraphrased, is what I was told by a friend (now one
of our tech support guys, formerly a kernel-hacking propellerhead):

"Stuff before the TOC is crap. Stuff after the TOC is meat.
Make the meat as meaty as possible. Make the crap as short
as possible. If I need to read and type at the same time,
make sure the book folds in half and lays flat."

John's advice resulted in my changing to wire-O binding and cutting
the preparatory material (manual title and copyright notices) to a
single sheet of paper. I also cut a lot of fluff from Chapter 1,
'Getting Started', which now contains:

About this manual
Who should use this guide
Management Overview
Benefits of <product>
<product> modules
Technical Overview
Installation, configuration & licensing
Starting <product>
Software environment & user interface
Conventions
For More Information

This runs to about 13-15 pages or 2000-2500 words, depending on the
product. I'd like it to be even shorter but I can live with that.
Previously I had a one-page preface/overview, then an Intro chapter,
then an Overview chapter, then zzzzzzzzzzzzz......

The idea is that with a five minute skim a manager could learn roughly
what the software is for and why it's worth all the money they paid,
and a techo/end user could learn "how much of a hassle is this going
to be to install? How badly is it going to mess up my nice tidy system?
What does it do anyway?"

Yours tersely
---
Stuart Burnfield
Functional Software Pty Ltd
mailto:slb -at- fs -dot- com -dot- au

TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot- Send commands
to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
Search the archives at http://www.documentation.com/ or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html


Previous by Author: Thanks... and need info on a cross-platform graphic format
Next by Author: Online Reviewing and Acrobat Exchange
Previous by Thread: Re: chapter numbering
Next by Thread: Re: chapter numbering


What this post helpful? Share it with friends and colleagues:

Sponsored Ads


Sponsored Ads