RE: Wording too dense? OK?

Subject: RE: Wording too dense? OK?
From: Stuart Burnfield <slb -at- westnet -dot- com -dot- au>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Date: Thu, 28 Jun 2007 10:34:41 +0800

Bonnie said:
> Trust the developer. Anyone using that doc *will* understand.

Yikes! You can't know that.

These instructions are written for a DBA who is familiar with Oracle and
UNIX shell scripts. Many of the readers may well be Oracle DBAs working
in a UNIX environment, but some might be:
- Experienced DBAs now working with Oracle for the first time.
- UNIX system admins taking on some DBA tasks for the first time.
- Experienced Oracle UNIX DBAs at your largest customer sites in Asia
or Europe. Their English is pretty good but they're not telepathic.
- Experienced Oracle DBAs now working on UNIX for the first time.

It's not your job to give them tutorials on UNIX, Oracle and database
admin concepts, but there are at least three easy things you can do:
- write each step as a simple statement (with a subject and verbs)
- use consistent formatting to distinguish variables and keywords
from normal text
- provide an example script showing all these statements

Bonnie gives an example:
> d. Point the FILDIR directory *to* where you want the
> database files to be created.

I read the original sentence three times before I spotted the missing
"to". Now I'm 95% sure I know what this instruction means. Why not make
the simple change to make it 100% clear the first time through?

I would definitely try to define an official list of representative user
types and get it OKed by the CEO and developer. It will save you a lot
of similar arguments in future. Then I would get this procedure tested
by some beta customers and in-house staff other than the main developer.
Installation and configuration is so important. The software might be
great, but you'll still lose sales if potential customers can't install
it correctly without much angst.


Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include support for Windows Vista & 2007
Microsoft Office, team authoring, plus more.

True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity!

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Previous by Author: Re: assessing a lone-writer gig
Next by Author: Burnfield's Corollary to Poncela's Assertion
Previous by Thread: Re: Wording too dense? OK?
Next by Thread: How about Keeping the List Civil? Was: Employment question

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

Sponsored Ads