Re: Doc Design and Convention ( was TECHWR-L Digest, Vol 48, Issue 27)

Subject: Re: Doc Design and Convention ( was TECHWR-L Digest, Vol 48, Issue 27)
From: Keith Hood <klhra -at- yahoo -dot- com>
To: "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>, Janice Gelb <Janice -dot- Gelb -at- Sun -dot- COM>
Date: Tue, 3 Nov 2009 16:51:18 -0800 (PST)

I think Paul's list is perfectly valid for a reference type of document, although 2 and 3 seem redundant to me.

Janice's list, to me, reads like it's closer to a marketing approach about deciding what to put in the documents. It seems predicated on putting more into thinking about the nature of the users.

I think for a procedural guide the list has to be different because the information has to serve different purposes. Here's my list for a procedural document, in no particular order:

1. What level of expertise can be expected of the user?

2. What is the user trying to do with the item?

3. What does the user need to know *before* he tries doing that? (Could be restated as, What are the traps the reader could fall into?)

4. What results should the user see when he does it right?

5. What should the reader do if something goes wrong? (This one is usually never answered, or answered indirectly at best by placing more emphasis on #3. The places I've worked, guidance on how to deal with errors is almost never included in any documentation, electronic or hard copy, because there isn't time to build in any fault tolerance.)


And, on a semi-cynical note, last but certainly not least:

6. What does the boss want in the document whether I think it makes sense or not? (I'll do my best to make a good case for what I think is the right way to do things, but when the boss says "Do it my way anyway," I salute and move out.)




--- On Tue, 11/3/09, Janice Gelb <Janice -dot- Gelb -at- Sun -dot- COM> wrote:

> From: Janice Gelb <Janice -dot- Gelb -at- Sun -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" <techwr-l -at- lists -dot- techwr-l -dot- com>
> Date: Tuesday, November 3, 2009, 3:54 PM
> Paul Hanson wrote:
> > Hanging on my cubicle wall:
> > |
> > When documenting something, you must answer the five
> golden questions:
> > 1) What is it?
> > 2) What does it do?
> > 3) What is its purpose?
> > 4) How does it work (or how does it do what it is
> supposed to do)?
> > 5) Why is it relevant?
> > |
> > Thought that'd be helpful.
> >
>
> I disagree with these questions - not all of
> these questions are ones that product users are
> interested in knowing. These questions are from
> the point of view of how to *document* the product,
> not from the point of view of how to *use* the product.
>
> Here are mine, off the top of my head:
>
> * Who is likely to be buying and using the product?
> * For what purposes are they buying and using the product?
> * What information do they need in order to use the
>    product effectively?
> * What is the best way to deliver that information for
>    these users?
> * What knowledge can I assume that most of these users
>    already have?
>
> -- Janice




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

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


Follow-Ups:

References:
Re: Doc Design and Convention ( was TECHWR-L Digest, Vol 48, Issue 27): From: Janice Gelb

Previous by Author: RE: Figures with numbered callouts
Next by Author: Re: Doc Design and Convention ( was TECHWR-L Digest, Vol 48, Issue 27)
Previous by Thread: Re: Doc Design and Convention ( was TECHWR-L Digest, Vol 48, Issue 27)
Next by Thread: Re: Doc Design and Convention ( was TECHWR-L Digest, Vol 48, Issue 27)


What this post helpful? Share it with friends and colleagues:

Sponsored Ads


Sponsored Ads