Re: Technical Review of documentation

Subject: Re: Technical Review of documentation
From: marjo -dot- kuusto -at- nokia -dot- com
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Fri, 9 Nov 2001 01:33:37 -0700

(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.



Previous by Author: RE: Tech Writing Curriculum
Next by Author: hotmail Spam not techwr-l Spam
Previous by Thread: Re: Technical Review of documentation
Next by Thread: Certifications


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


Sponsored Ads