TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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.
Stuart
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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. http://www.DocToHelp.com/TechwrlList
True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
