RE: Initial Doc Focus: Concepts or Procedures?

["McLauchlan, Kevin" <Kevin -dot- McLauchlan -at- safenet-inc -dot- com>]

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-
> l.com] 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
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.
> 
> 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
after
> each function that the user might encounter
>    -- relating all functions and groupings of functions to actual
TASKS
> that the users would need or want to accomplish
>    -- explaining all terminology with which a user might not be
familiar
> 
>  - provides a clear and unambiguous beginning and end for each task
> (clump of vaguely-related functions/operations), so that the user
knows
> 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
everything
> 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
outside
> 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.
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.