Re: Initial Doc Focus: Concepts or Procedures?

Subject: Re: Initial Doc Focus: Concepts or Procedures?
From: "Pro TechWriter" <pro -dot- techwriter -at- gmail -dot- com>
To: "Mike Starr" <mikestarr-techwr-l -at- writestarr -dot- com>
Date: Thu, 24 Jul 2008 10:32:50 -0500

Good stuff, Mike. Thanks. See my responses below:

On Thu, Jul 24, 2008 at 4:43 AM, Mike Starr <
mikestarr-techwr-l -at- writestarr -dot- com> wrote:

> IMNSHO, good (and *complete*) software documentation requires (in the
> following order):
> * Introduction that includes some of both *isn't the product wonderful*
> text and *basic concepts* text as well as a *brief overview* of the user
> interface. The *isn't the product wonderful* text and *basic concepts* text
> can help sell the product to folks who are evaluating it (you do want your
> company to be able to actually *sell* this product, don't you?).

Oh, absolutely. There is some of this now, I just wanted to make sure
procedures for actually using the software are there too.

> * Common procedures section that provides step-by-step descriptions of how
> the user accomplishes the most common tasks.

Yes, this is there.

> * Reference section that describes each available menu item, toolbar,
> dialog box, etc. With the miracle of *single sourcing*, the reference
> section can be the foundation of the help file that provides
> context-sensitive help for all of these things.

Included also, and isn't single sourcing wonderful?

> In addition, system requirements and installation instructions are a
> necessity as well but possibly not in documentation that's only available
> after the product has been installed.

> System requirements definitely belong in the marketing literature and on
> the company website but I have also included them in the Introduction
> section of user manuals as well with the assumption that the user manual may
> be used as part of the marketing material (via the website or through sales
> folk).
This is great advice, and you are the second person who has suggested it, so
it's going in there.

> Installation instructions should be available on the company website and as
> printed material if the product is physically shipped; I sometimes include
> them as an appendix in the user manual.

It's not shipped, but is hosted. Not sure about printed vs. online--we may
have both.

> The documentation may also require a glossary, especially if you use terms
> and/or acronyms that new users may not be familiar with. I have at times
> included a glossary as part of the introduction section and at other times
> as an appendix.

Our stuff comes with a glossary, so that is included too.

> Best regards,
> Mike
> --
> Mike Starr WriteStarr Information Services
> Technical Writer - Online Help Developer - Technical Illustrator
> Graphic Designer - Desktop Publisher - MS Office Expert
> (262) 694-1028 - mike -at- writestarr -dot- com -
> 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.
>> PT

Dale Carnegie wrote in his famous book 'How to Win Friends and Influence
People,' that our deepest human desire is to believe we are a good person."

-- Rabbi Schmuley

Tell your kids they are >good< people.

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
Re: Initial Doc Focus: Concepts or Procedures?: From: Mike Starr

Previous by Author: Initial Doc Focus: Concepts or Procedures?
Next by Author: Re: Coworker who won't take no for an answer
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