Technical reviews

Subject: Technical reviews
From: "Peter Ring, PRC" <prc -at- PIP -dot- DKNET -dot- DK>
Date: Tue, 22 Oct 1996 11:41:13 +1

On Mon, 21 Oct 1996 Wendy Carvell <wcarvell -at- ENVIRO -dot- COM> wrote

> I'm interested in getting feedback around what questions you would
> include on a technical review sheet. I often give chapters of the
> manual to our engineers and would like to build a nice list that
> would guide them in their review efforts. I seem to think that they
> are confused and not sure what they should look for in the
> document.

It is very simple!

The engineers should look for ...

1. Technical errors

2. Missing technical information (text, drawings, etc.)

... ONLY!

You may add some additional questions about details specific to the
actual product.

The usability of the manual should be tested with a usability test,
done by persons representing the profile(s) of typical users.

And then three advises to yourself:

- NEVER let you influence from the engineers to include technical
details not needed by the type of users, this manual was written
for. If e.g. a procedure can be made in 15 different ways, and you
have chosen to describe one or two of them only, don't let the
engineer persuade you to include the remaining 13-14 ways. But if
you are ordered to do so, put them away in an appendix.

- NEVER let you influence from the engineers change the language to
a more academical or technical language. All the readers of your
manuals should be able to understand it!

- Don't forget to explain to the users, what the product is doing, -
including (if relevant for the users) a POPULAR description of how
it works. This information is very often missing in the
documentation from the engineers to the technical writer. Reason:
to the engineer, it is obvious. But to the user it is very often
absolutely not obvious!

Greetings from Denmark

Peter Ring
PRC (Peter Ring Consultants)
- specialists in user friendly manuals and audits on manuals.
prc -at- pip -dot- dknet -dot- dk
- the "User Friendly Manuals" website with links, bibliography,
list of prof. associations, and tips for technical writers.

Previous by Author: Translation and Internationalization Issues
Next by Author: acceptable error rates
Previous by Thread: Technical reviews
Next by Thread: Canadian Technical Writing Companies....

What this post helpful? Share it with friends and colleagues:

Sponsored Ads