TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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-
