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, Robert Lauriston <robert -at- lauriston -dot- com>
Date: Thu, 5 Nov 2009 06:37:33 -0800 (PST)

Once again, I must emphasize that when I wrote about my thinking on what to put in a technical document, I WAS REFERRING ONLY TO PROCEDURAL DOCUMENTS. As in documents that tell the user what steps to take in order to perform actions with the item, as opposed to documents that tell the user *about* the item. You seem to be unwilling or unable to understand the distinction.

The questions about why a user would want the thing and what they hope to accomplish with it, and the effect the answers have on the document being produced, are variable. They depend on the type of document being done. A white paper is almost completely based on thinking about business aspects of how the thing fits into the user's business model. Online help is almost completely based on thinking about how the thing is used as a tool.

It is NOT a one size fits all matter. There is a spectrum of concern when thinking about what to put in a document and how to arrange it. On one end of the spectrum, an executive summary is almost entirely - to coin a phrase - marketing speak, and on the other end of the spectrum, a quick start card is almost entirely tech speak. Their natures are so different, the writer must consider different factors when writing them.

The reader of an executive summary does not care which button the user pushes in order to do something. He cares about how the thing will improve his business situation. So deciding what to put in his document is weighted toward the business end of the scale. The user who is trying to employ the item to accomplish some task and is in a hurry is very much concerned about which button to push next, and he could not possibly care less what business advantages his boss sees in the thing. So deciding what to put in his document is weighted toward the technical end of the scale. And since there are significant differences in what those people will want and need in their documents, the questions to ask about what information to give them will be different, and the types of answers formulated for those questions will be different.

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.

How many different ways do I have to state it before it finally gets through?


--- On Wed, 11/4/09, Robert Lauriston <robert -at- lauriston -dot- com> wrote:

> From: Robert Lauriston <robert -at- lauriston -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: Wednesday, November 4, 2009, 2:58 PM
> I agree that a good technical writer
> should think that way. It's not
> either/or: that's one of the places where our work overlaps
> to some
> extent with marketing.
>
> I said that in response to Keith Hood, who seems to be
> arguing against
> it. That's a substantive issue, not semantics:
>
> "... it seemed to me your thinking about the users was more
> closely
> related than mine to the way in which a marketing person
> would think
> about the users. Your second question was, "For what
> purposes are they
> buying and using the product?" That's broader in scope than
> the kind
> of questions I ask, and seemed to indicate thinking about
> how the
> users see the item fitting into their business. That way
> of
> considering user concerns about the item isn't related
> strictly to the
> technical aspects of the item. When I think about why users
> may want
> the item, I tend to consider it more as a matter of tool
> use. I think
> my way of looking at user needs and concerns is more
> tightly focused,
> that's all. And please remember that I'm talking here only
> about doing
> procedural documentation. For reference materials, or for
> documents
> that are more business related, like requirements or white
> papers, my
> approach to deciding what to put in the docs would look
> more like what
> you and Paul wrote. ..."
>
> On Wed, Nov 4, 2009 at 11:37 AM, Gene Kim-Eng <techwr -at- genek -dot- com>
> wrote:
> > It would appear we only have a semantics issue.
> >
> > I don't see creating documents that "reflect the
> specific business
> > requirements of prospective customers and a contextual
> understanding of how,
> > by whom, and for what purposes the product is used" as
> thinking like a
> > marketer.  I see it as thinking like a technical
> writer.
> >
> > Gene Kim-Eng
> >
> >
> > ----- Original Message ----- From: "Robert Lauriston"
> <robert -at- lauriston -dot- com>
> > To: <techwr-l -at- lists -dot- techwr-l -dot- com>
> > Sent: Wednesday, November 04, 2009 11:01 AM
> > Subject: Re: Doc Design and Convention ( was TECHWR-L
> Digest, Vol 48, Issue
> > 27)
> >
> >
> > I didn't say anything of the sort. Marketing hype
> doesn't belong in
> > technical documentation. I never use any marketing
> language except
> > sometimes in the first few paragraphs of a user's
> guide and release
> > notes, and even there I tone it down and cut anything
> that's not
> > supported by the facts.
> >
> > Documentation that reflects the specific business
> requirements of
> > prospective customers and a contextual understanding
> of how, by whom,
> > and for what purposes the product is used is a helpful
> tool for anyone
> > evaluating the product, especially when installation
> is a long and
> > complex process (as is usually the case for
> client-server and
> > Web-based applications, especially those that require
> a third-party
> > database such as Oracle or SQL Server). It helps the
> prospective buyer
> > understand whether the product would meet their
> needs.
> >
> > I know that's true from the buyer's side as well. If
> it's too much
> > trouble to install a product and I can't tell from the
> docs whether it
> > will do the specific things I need it do, I'll move on
> to the next
> > candidate.
> >
> >
> >
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> 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


Follow-Ups:

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

Previous by Author: Re: Doc Design and Convention ( was TECHWR-L Digest, Vol 48, Issue 27)
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