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: voxwoman <voxwoman -at- gmail -dot- com>
To: Keith Hood <klhra -at- yahoo -dot- com>
Date: Wed, 4 Nov 2009 13:29:42 -0500

Exactly. If I can be so bold as to use a physical object example: When I
buy a clock or a blender, I want to know how to set the time or how to make
a smoothie (these require a procedure to perform successfully). I also want
to know if the clock will continue to operate during a power failure, or
that I have to put the blender lid in the top rack of the dishwasher (which
come under the heading of important information I might like to know). The
"marketing focus" would be more along the lines of if either design won an
award, or how the features compare to competing products, which don't really
belong in the user's manual, but I'd expect them to appear someplace in the
advertising or the product packaging.

-Wendy

On Wed, Nov 4, 2009 at 12:42 PM, Keith Hood <klhra -at- yahoo -dot- com> wrote:

> I cannot emphasis this strongly enough: When I wrote about what I thought
> of when deciding what to put in a doc, I was speaking specifically about
> PROCEDURAL documents. That means things like online help and software user
> guides, things that are intended for the specific purpose of telling the
> user how to do things. I approach the matter of deciding what to put in
> those as a matter of thinking about tool use, because those documents are
> about tool use. Such things can be a kind of marketing ploy but their
> primary purpose above all else is to tell the user how to do things.
>
> If I were writing a reference document I would provide background
> information instead of do-this-do-that procedures. If I were writing a white
> paper or an executive summary the audience would be different and my
> consideration of what to put in the document would be different. If I were
> drawing network topology diagrams I would ask only one question: what does
> the network look like? When I set down that list, I was not advocating a one
> size fits all approach. I was talking about thinking on the subject of
> making how-to procedural papers. I now seems to me I didn't make that clear
> enough. Maybe in the future I'll try all caps.
>
> That said, I disagree with your last statement. I am a good technical
> writer - I've been doing it for 20 years - and I don't think like a
> marketer. Thinking like a marketer is the marketer's job. It's my job first
> and foremost to ensure the document - whatever flavor it is - serves the
> customer's needs for technical guidance, and then to try to satisfy the
> other stakeholders. My job where marketing is concerned is to coordinate
> with the marketer and the manager to ensure the resulting documents have the
> right look and feel, and language, to help support marketing concerns, but
> are still usable as technical documents. If the document is based entirely
> on marketing concerns, it's not a technical document, it's a white paper.
> That's a different kettle of fish and different concerns apply.
>
> As for excluding industry-specific warnings and things like that, that may
> be a problem if I were writing about industry-specific things and I forgot.
> But I don't think there are any industry-specific warnings to put in brand
> new software that's never been seen before and doesn't apply to any
> particular industry. Such warnings are almost never a concern for me.
>
>
> --- On Wed, 11/4/09, Robert Lauriston <robert -at- lauriston -dot- com> wrote:
>
> > By focusing narrowly on technical
> > concerns you're excluding the
> > specific business contexts in which the tool will be used
> > and thus
> > perhaps industry-specific warnings and tips that could be
> > helpful to
> > users.
> >
> > Whether that matters probably depends on how varied the
> > product's uses
> > are in practice.
> >
> > Also, a good technical writer should think like a marketer
> > to the
> > extent that the docs may be used as presales tools.
> >
>
>
>
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> 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 voxwoman -at- gmail -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/voxwoman%40gmail.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


References:
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: Keith Hood

Previous by Author: Re: 508 Compliance - Common Readability Issues
Next by Author: Re: tifs at 240 dpi worth redoing?
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