Re: Initial Doc Focus: Concepts or Procedures?

Subject: Re: Initial Doc Focus: Concepts or Procedures?
From: Janice Gelb <Janice -dot- Gelb -at- Sun -dot- COM>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Date: Thu, 24 Jul 2008 10:50:03 +1000

Pro TechWriter wrote:
> Hey Whirlers:
> I have a very short time frame to produce some documentation for some beta
> software.
> My thoughts that the users will need instructions to use the software, with
> some basic concepts related to the tasks thrown in. Some folks (um,
> "programmers") disagree with that approach. They want high-level conceptual
> information instead and some "isn't the product wonderful" text. They
> basically said "we don't need no stinkin' steps."
> Weigh in, please. I am interesting in hearing some *technical writer's*
> experience and opinions on this one.

Procedures. No question. Tell your programmers that
there's a reason that books are called "MyProduct
User's Guide" and not "The Joys of MyProduct" :->

Seriously, users can't appreciate how wonderful
the product is if they can't figure out how to
use it. No one buys a product to admire the design
or the clever coding. They buy products because
the product enables them to accomplish something.

Tell them that proper place for glowing descriptions
of the wonderfulness of the product is marketing
brochures and the web site.

-- Janice

Janice Gelb | The only connection Sun has with
janice -dot- gelb -at- sun -dot- com | this message is the return address


Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include support for Windows Vista & 2007
Microsoft Office, team authoring, plus more.

True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity!

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

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 for more resources and info.


Initial Doc Focus: Concepts or Procedures?: From: Pro TechWriter

Previous by Author: The Daily Show on Quotation Marks
Next by Author: Typo of the Year
Previous by Thread: Re: Initial Doc Focus: Concepts or Procedures?
Next by Thread: Re: Initial Doc Focus: Concepts or Procedures?

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

Sponsored Ads