Re: Initial Doc Focus: Concepts or Procedures?

["Pro TechWriter" <pro -dot- techwriter -at- gmail -dot- com>]

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.
>
Included.

>
> 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  -  http://www.writestarr.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.
http://www.DocToHelp.com/TechwrlList

True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! 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.