Re: Documentation Correctness was Re: How many levels of indents and heads are reasonable?

[stevefjong -at- comcast -dot- net]

     Having taught task-based documentation, I am tempted to try and reconstruct (or perhaps construct) what Mr. Lewis is talking about. I've hesitated up to now because (1) it's not clear whether he's ever actually described what he's talking about, made worse for me because (2) after the multiple-handle flap, I've ignored all his posts.
     That said, my tech writer's brain is foolishly eager to fill in the gaps and explain what I encounter, whether my mental model is right or wrong. So here goes...
     Tasks, as described by the IBM model, requires an actor, a series of actions, a starting point, and an ending point. Passive voice leads to confusion about the actor; sloppy writing (or not trying the task yourself) leads to step errors. But we also frequently elide the starting and ending points, not rigidly defining where you begin and when to stop, nor what you have when you're finished. Leaving out those elements can lead to other errors, possibly the ones to which What's-His-Name frequently alludes.
     For example, imagine that you are documenting how to set up your product to communicate with an external database. Imagine you have an engineering specification that says the last task is to configure the product with the IP address of the database. You document that task: say, what form to use, and what fields on the form you need to fill in. Finally, let's say you have access to the software and a test database, and you try the procedure as you write it. You are given the IP address of the database, and it's reasonable that the end user would have this information. But you have no idea what another field is or where you would get the information. The engineer says breezily, "Just enter 'TEST.'" You do it, but things still don't work--the product returns an error message that the database is not found on Port 1024.
     This is an elaborate setup; to simplify, I'm giving you an all-too-common scenario where you don't have the starting and ending points right. There is an implicit extra procedure before you can begin the task of setting up the link to the external database, and that is to establish a privilege group; you need to know the privilege group name before you can perform this task. (Or whatever--you know what I mean.) And after you set up the connection, you have to configure your firewall to permit access on port 1024. (Or whatever--you know what I mean.)
     A more formal task analysis would reveal that you need more information to begin the task, and you need to do (at least) one more thing before you complete the task. That's task-analysis speak.
     A data flow analysis might reveal that the task requires an additional input, and that the outputs of the task are not sufficient. Engineers commonly forget that they know something end users don't, which allows them to complete a task the rest of us can't.  I don't know that we as writers commonly butt one task against the next to check for information seepage.
     I wonder if this is the mystery.

          -- Steve
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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.