RE: Initial Doc Focus: Concepts or Procedures?

Subject: RE: Initial Doc Focus: Concepts or Procedures?
From: "McLauchlan, Kevin" <Kevin -dot- McLauchlan -at- safenet-inc -dot- com>
To: "McLauchlan, Kevin" <Kevin -dot- McLauchlan -at- safenet-inc -dot- com>, "Pro TechWriter" <pro -dot- techwriter -at- gmail -dot- com>, <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Thu, 24 Jul 2008 10:44:27 -0400

By the way, I wrote my little not-really-tongue-in-cheek post below from
the perspective of Beta tests at my company.

We send out Alphas with little/no documentation, because of the tight
cooperation with the alpha-testers, as somebody else on this list
described their conception of a beta-test program.

We send out Betas as release candidates. That means they have
pretty-much the final customer documentation accompanying the
pretty-much final software and hardware.

That alpha-beta distinction is why I approached the issue the way that I
did, and why my approach differs from that of some other posters. To my
mind, they were describing alpha testing, not beta. YMMV

- Kevin

> -----Original Message-----
> From:
techwr-l-bounces+kevin -dot- mclauchlan=safenet-inc -dot- com -at- lists -dot- techwr-l -dot- com
[mailto:techwr-l-bounces+kevin -dot- mclauchlan=safenet-inc -dot- com -at- lists -dot- techwr-
>] On Behalf Of McLauchlan, Kevin
> Sent: Thursday, July 24, 2008 10:22
> To: Pro TechWriter; techwr-l -at- lists -dot- techwr-l -dot- com
> Subject: RE: Initial Doc Focus: Concepts or Procedures?
> On Behalf Of Pro TechWriter
> > Sent: Wednesday, July 23, 2008 19:52
> > Hey Whirlers:
> >
> > I have a very short time frame to produce some documentation for
> 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.
> > 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.
> I think that your programmer friends are entirely correct...
> as long as the application:
> - documents itself, including
> -- saying WHY you want to use each feature
> -- pointing to all possible other functions that might be used
> each function that the user might encounter
> -- relating all functions and groupings of functions to actual
> that the users would need or want to accomplish
> -- explaining all terminology with which a user might not be
> - provides a clear and unambiguous beginning and end for each task
> (clump of vaguely-related functions/operations), so that the user
> what, if anything, they are supposed to do next, and why
> - is completely and reliably consistent throughout the interface, in
> terms of terminology, interface elements and controls, etc.
> - is completely and reliably correct throughout the interface
> works as expected, is spelled correctly, and so on.
> - is complete - accommodates all tasks that a user might conceivably
> attempt to accomplish in the well-defined (and explained) milieu to
> which the app is directed, fully and comprehensively, while detecting
> unsupported attempts and explaining why this or that odd task is
> the scope (see next item)
> - traps ALL conceivable (and quite a large number of inconceivable)
> errors and presents cogent, informative and useful error messages for
> every one (with no conflicts and no ambiguity for a naive user (so no
> use of jargon), ever)
> - is idiot-proof.
> And, of course, as long as they are willing to guarantee the above in
> writing so that you have a signed memo to wave at the root-cause
> investigations and lawsuits... oh, and they need to indemnify you for
> any losses you might suffer as a result of complying with their
> assertions and demands.
> The above is a first draft. Others will add performance requirements
> that the software must meet if it's to go out with as little
> "documentation" as your programmers are demanding.
> - Kevin

The information contained in this electronic mail transmission
may be privileged and confidential, and therefore, protected
from disclosure. If you have received this communication in
error, please notify us immediately by replying to this
message and deleting it from your computer without copying
or disclosing it.


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: McLauchlan, Kevin

Previous by Author: RE: Initial Doc Focus: Concepts or Procedures?
Next by Author: [TOOLS] Review/user comments of MS Virtual Destop Manager powertoy
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