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

[Keith Hood <klhra -at- yahoo -dot- com>]

Gene, your argument about liability applies only to a very small fraction of the work done by technical writers. Yes there are sometimes valid worries about liability. But most technical writers never have to deal with medical software or something where the instructions could be literally a matter of life and death.

And, remember the *scale* of the thing we're talking about here. We're not talking about writing a manual for a CAT scan machine in iambic pentameter. We're not talking about DNA test instructions written in Chinglish. We're talking about things like whether or not to bother mentioning it when a new window opens.

That being said, we proceed...



> Anything that can arguably be said to have created
> confusion in the mind of the reader about any part of
> a document can potentially be woven into an argument
> a lay jury will buy.

And that case can also be won. The key word here is "arguably." Anything an be argued but when it's pretty easy to show that a person of normal intelligence can handle something.

And no, it's hardly "any" part of the document. It would have to be a part of the document that is directly related to performing some action correctly or not. AND, the plaintiff's lawyer would have to prove that the incorrectness of the action is a contributing cause to whatever harm it was they claim was done.  The only lawyer who would try to make a case about the instructions being tragically flawed on grounds like the index wasn't very good, or the headers and footers were muddled, is a squirrel case lawyer - one who tries desperate measures and argues points that are ridiculously stilted because he isn't very good. This would be a "twinkie defense" sort of case. Just about anyone could win against a lawyer like that.



> Any conceivable creativity in tech
> writing is dwarfed by the creativity of trial lawyers.

Wanna bet? Try me. :-)



> I would question whether it is always necessary to tell the
> user that a particular dialog is going to appear,
> especially
> if the instruction that makes it appear is followed by a
> next step that tells the user to do something in that
> dialog
> along with a figure that shows the dialog complete with
> its title bar.

I never said it was "always" necessary. In fact, I never used the word "necessary." What I said was, there are times when variations are OK, and there are times when naming screen features is useful.



> Instead of saying 1) do this, 2) the xxx dialog appears,
> 3) do this in the xxx dialog, just leave out step 2 and see
> if it still makes sense.

I don't do it that way. There would be absolutely no point in having a numbered step in a procedure that does nothing but name a screen feature. I do it something like this:
1) Do X - the Y wizard appears.
2) D Z.

And every step is, whenever possible, accompanied by a screen cap that shows *where* they do X or whatever. I'm a big believer in illustrations, and being a commercial art major, putting in lots of screen caps and graphs and figures and such allows me to indulge my delusions of artistry.



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

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.