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: Robert Lauriston <robert -at- lauriston -dot- com>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Date: Wed, 4 Nov 2009 11:58:42 -0800

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 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
Re: Doc Design and Convention ( was TECHWR-L Digest, Vol 48, Issue 27): From: Keith Hood
Re: Doc Design and Convention ( was TECHWR-L Digest, Vol 48, Issue 27): From: Robert Lauriston
Re: Doc Design and Convention ( was TECHWR-L Digest, Vol 48, Issue 27): From: Gene Kim-Eng
Re: Doc Design and Convention ( was TECHWR-L Digest, Vol 48, Issue 27): From: Robert Lauriston
Re: Doc Design and Convention ( was TECHWR-L Digest, Vol 48, Issue 27): From: Gene Kim-Eng

Previous by Author: Re: screencasts tool preference
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