TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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-
