Re: Technical Review of documentation

[marjo -dot- kuusto -at- nokia -dot- com]

(sorry, longish)

Hi,

I have used at some point a letter stressing what 
to pay attention to (i.e. not grammar) and more 
recently a checklist, here are some samples from 
the checklist. Not all points are relevant to 
all types of documents and anyway, you may not 
want to give the SMEs a long checklist as it may 
scare them... So just ask them to pay attention 
to the most important things.

- All aspects of the product which are relevant to the user are covered.
- No information which is essential to the user is missing from the
document.
- Information which is unnecessary to the user has been removed from the
document.
- The document explains the technical background issues in enough detail.
- There is no information which must not go to the customer in the
document.
- The document contains information on how to exploit advanced features of
the application.
- The document contains all the necessary recommendations, preconditions,
requirements and skills (for example on operating environment,
technologies).
- All necessary warnings and cautions are in place.
- All dependencies between features, commands, parameters etc. are
described.
- All database tables, processes, commands, files etc. are defined and
correct.
- All commands are correct. 
- There are examples in places where reader may need them to help, and
they are suitable and correct.
- Problem-solving information is provided on problems that users may have.
- Solutions to the problems are provided.
- All information in graphics and tables is correct.
- Are there any tips and hints on using the product that could be added to
the document?
- All text in the document is understandable (anything you do not
understand users may not understand either).
- Have you received any feedback from customer related to the document,
documentation in general or the product, which could be implemented in the
document?
- All possible user tasks are described. 
- All task sequences are correct (all preconditions, steps, and outcomes
in correct order).
- All procedures and commands in the document have been/will be tested.
- The tasks are presented in a logical order and in a logical hierarchy
which answer to user's questions ("how do I do X?").
- There are process descriptions (flowcharts) that put the tasks in
context.
- All user interface components are explained and the descriptions are
correct.
- All terms in the document and in the user interface are identical.
- The document guides the user if the user interface does not give enough
information on how to proceed.

Hope this helps,
Marjo

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Be a published author!  iUniverse gives you: a high-quality paperback, a
custom cover design, and distribution to 25,00 retailers.  Join our almost
10,000 published authors today. http://www.iuniverse.com/media/techwr

  Your monthly sponsorship message here reaches more than
  5000 technical writers, providing 2,500,000+ monthly impressions.
  Contact Eric (ejray -at- raycomm -dot- com) for details and availability.

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit 
http://www.raycomm.com/techwhirl/ for more resources and info.