Re: A philosophical tech writing question

[Peter Neilson <neilson -at- windstream -dot- net>]

Keith Hood wrote:
> --- On Thu, 11/20/08, Ned Bedinger <doc -at- edwordsmith -dot- com> wrote:

>> Personally, I could enjoy good documentation written or
>> assembled by a computer. ...

> = I really think that day will never arrive. True computer-generated
> = writing would require a very precise model of how the writing mind 
> = works. ...

I have already seen the documentation written by a computer, or else by 
someone whose mind could have been replaced by one. It tends to name the 
function of each part, but omit overviews and goals. An example (I'm 
making this one up) might go like this:

*******************************************************************
Using the mouse, click on the buttons for actions.
[picture of mouse omitted]
[picture of DATA button omitted]
DATA > ACTIONS > XSORT Displays xsort options
DATA > ACTIONS > XSORT > QS Displays the quicksort selection page.
*******************************************************************

The poor user, through trial and error, and without the help of the 
badly focused documentation, has already reached the QS page, but cannot 
figure out how to get QS to sort by the data in the third column. (It's 
trivial--you enter -2 in the OTHER OPTIONS box. The computer who wrote 
the documentation saw no need to include that "obvious" part.)

The choices of what to put in, how to describe it, and what to leave out 
are part of what distinguish good documentation from bad. But I'm 
preaching to the choir.

It's almost Friday, so I'd better remind everyone that if there are 25 
sheets in a quire, and 500 in a ream, we might be able to calculate the 
number of choirs in a trireme.


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

ComponentOne Doc-To-Help 2009 is your all-in-one authoring and publishing 
solution. Author in Doc-To-Help's XML-based editor,  Microsoft Word or 
HTML and publish to the Web, Help systems or printed manuals. 
http://www.doctohelp.com

Help & Manual 5: The complete help authoring tool for individual
authors and teams. Professional power, intuitive interface. Write
once, publish to 8 formats. Multi-user authoring and version control! 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. 

Please move off-topic discussions to the Chat list, at:
http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat