Re: Doc Design and Convention - to address Gene's take on this

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

Gene, when you think about what to put in a document, apparently you ask yourself the same set of questions no matter what the document type, but you formulate the answers differently for different types of documents. When I think about what to put in a document, I ask myself a different set of questions for each different type of document. The end result - a determination about what to put in the document - is the same. Six of one, eight minus two of the other. Big deal.

The main issue is to make the resulting documents serve the customers' needs. This is an art, not a science, and there is plenty of room for variance in the thinking about how things are done. The biggest question of all to ask about a technical document is, does it work? Even though I apparently think in a different manner, the employers for whom I have written answer that question with the word "Yes."

This is all I have to say on this matter. I am tired and this message is my last post on this topic.


--- On Thu, 11/5/09, Gene Kim-Eng <techwr -at- genek -dot- com> wrote:

> From: Gene Kim-Eng <techwr -at- genek -dot- com>
> Subject: Re: Doc Design and Convention ( was TECHWR-L Digest, Vol 48, Issue  27)
> To: techwr-l -at- lists -dot- techwr-l -dot- com
> Date: Thursday, November 5, 2009, 11:42 AM
> This is the part I disagree
> with.  The questions that need to be asked are the 
> same for all documents.  What is different for
> different documents is the extent 
> to which the answers influence the form and content of the
> document.  You may 
> not be writing about the "business aspects" of what the
> product is designed to 
> do, why the customer/user wants the product or what the
> customer/user wants to 
> accomplish with the product, but you still need to ask
> about these things and 
> know what they are, because they determine (or should
> determine) how the 
> procedural information is presented and organized, or in
> some cases whether 
> certain procedural information is provided at all.
> 
> I have a shelf full of ponderous tomes masquerading as
> software user manuals 
> that document every function their applications are capable
> of performing, with 
> no distinction made between those functions that serve the
> needs of the most 
> common "bread and butter" paying customers and those that
> are of interest only 
> to the most advanced power users.  In some cases, the
> companies that made the 
> applications have long since eliminated their printed
> documents, laid off their 
> in-house writers and now only provide offshore-produced
> online help, with the 
> result being equally useless because I can't find the help
> for a command until 
> after I've managed to find where the command is buried in
> the UI.  In all of 
> these cases, I can usually type the name of the application
> and my specific 
> question into Google and find the answer I need posted by
> some other equally 
> frustrated user who finally managed to figure it out faster
> than I can find it 
> in either the printed manuals or the online help.  I
> don't know if the problem 
> with these documents is that their writers failed to ask
> about the "business 
> aspects" of the products, or if they just documented
> everything in sight as 
> "defensive writing" because the company's developers and
> product managers 
> couldn't answer those questions, but either way the result
> is some of the worst 
> user documentation I have ever encountered and is all but
> worthless to me as a 
> customer/user (though I do sometimes make use of them as
> examples of how not to 
> write when coaching new writers).
> 
> Gene Kim-Eng
> 
> 
> 
> ----- Original Message ----- 
> From: "Keith Hood" <klhra -at- yahoo -dot- com>
> It is a matter of asking different questions for different
> documents, because 
> they do not serve the same purposes, so the thinking about
> how to structure them 
> is different.
> 
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> 
> Are you looking for one documentation tool that does it
> all? Author, 
> build, test, and publish your Help files with just one
> easy-to-use tool.
> Try the latest Doc-To-Help 2009 v3 risk-free for 30-days
> at:
> 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 klhra -at- yahoo -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/klhra%40yahoo.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
> 
> 


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

Are you looking for one documentation tool that does it all? Author, 
build, test, and publish your Help files with just one easy-to-use tool.
Try the latest Doc-To-Help 2009 v3 risk-free for 30-days at:
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