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.
It does really depend on the users of the software. If experience and
computer savviness is required for using the software, you can be very
terse. In this case, the "describe all in fullest and widest and longest
detail" style could even be considered to be an insult.
On the other hand, if the softare is used by absolute beginneers, you will
have to write everything in full detail.
One possibility (which I have used in some cases) is to have a chapter
where the basic actions (opening a menu, selecting in a dialog box etc.)
are explained in full detail, and the rest of the documentation then was
based on these basic steps.
You implicitely say it in your message. Consider the users. Maybe even try
to get in touch with representative users. Talk to them. Learn how they
work.
Added later: You say in a follow-up message that the documentation got some
harsh comments that it did not provide enough detail. Was that on the way
the software had to be used, or was that on the options and functionality
of the software?
Hope, this can help.
Max Wyss
PRODOK Engineering AG
Technical documentation and translations, Electronic Publishing
CH-8906 Bonstetten, Switzerland
Fax: +41 1 700 20 37
e-mail: mailto:prodok -at- prodok -dot- ch or 100012 -dot- 44 -at- compuserve -dot- com
Bridging the Knowledge Gap ...
... with Acrobat Forms ... now for belt drive designers at
>Hi folks,
>
>
>I work in a software development company, and recently
>ran facefirst into a cream pie -- the pie, in this case, was
>the debate about whether we can trim our user documen-
>tation down to "essentials" because our users are "too
>sophisticated" to require background information (in this
>case, complete step-by-step instructions).
>
>The root of the problem seems to be the writing style I've
>chosen for our documentation. I made a decision (based
>on what I saw other software companies doing with their
>documents) to write instuctions in full sentences using
>bold type to identify buttons, menus, menu commands, and
>other inputs. An example of this would be "From the
><b>Edit</b> menu, select <b>Merge</b>." I usually tie
>these step-by-step instructions to a task that the user
>needs to complete.
>
>
>
>Yes, I am familiar with the rule "satisfy the user/client" and I
>am trying to do that. I don't think that our developers are our
>users/clients. The documentation shouldn't be written to
>satisfy people who are already familiar with our software, it
>should be written to satisfy people who've never used it before.
>However, programmers are programmers, and I don't want to
>ignore feedback saying that the documentation is too wordy
>or talks down to our users.
>
>Do you think I should drop the full sentence instructions and
>try something like "Edit --> Merge" ? This would satisfy our
>developer's desire for brevity, but it isn't exactly elegant.
>
>Any suggestions? If you've developed a particular style-based
>solution, could you send me examples?
>
>Thanks again, folks,
>
>Rowena :-)
>
>
