RE: Variety in Tech Writing (was: Display, Displays, or Appears)

["Lauren" <lauren -at- writeco -dot- net>]

Some apps have bad instructions and some instructions are for bad apps.  I
just try to account for possible issues that can arise.  I generally do not
use phrases like, "the xxx dialog appears," but I do try to address the fact
that one task should launch a new window.  I guess in your example, the
existence of the appropriate window is implied, but to arbitrarily say to
leave out the step that the window appears could inadvertently leave out the
implication that the window has spawned.  <ooh, look, three terms to
reference the same element, and all in one paragraph.  "Launch," "appears,"
and "spawns."  I'm so bad.>

Gene, is what follows an example of your suggestion?  I would write a
procedure like this.  Each step results in some action, so if a step is
performed and nothing happens, then the user will know that there is an
error.  I've had instructions refer to a window, but there was no reference
for how that window was opened (another term?) and stepping back through
instructions was not insightful.  Like in Word, sometimes there is a
reference to a widget from the x menu, but no reference to getting to the
menu that lets me know why I can't see the menu.  I realize that is the
product of bad writing, but the bad writing of other authors leads me to get
picky about my own writing.  Also notice in my example that the final step
concludes with the procedure's name to indicate completion of the procedure.
I think that sort of thing is helpful when it is feasible.

To Print
--------
1. Click "File" from the toolbar.
2. Select and click "Print..." from the dropdown list.
3. Choose print options from the print window.
4. Click "OK" to print.

Lauren

> -----Original Message-----
> From: Gene Kim-Eng

> I don't know if this is giving readers too much credit or
> not enough, but I would think that telling someone to do
> something in one dialog followed by an instruction to
> do something in the next dialog would tell them that the
> next dialog is what is supposed to come up, and that
> anyone who doesn't realize there's been a application
> failure when they follow instructions and the next dialog
> doesn't come up isn't necessarily going to realize it
> when the document says "the xxx dialog appears" and
> it doesn't.
> 
> Gene Kim-Eng
> 

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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- 

To unsubscribe send a blank email to 
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


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
http://www.techwr-l.com/ for more resources and info.