Is there such a thing as TMI?

Subject: Is there such a thing as TMI?
From: "Jane Carnall" <jane -dot- carnall -at- digitalbridges -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 19 Mar 2002 17:24:35 -0000

Is there such a thing as giving people too much information?

Well, if the people are being given more information than they can handle
(or is that bad design?) or if they are being given irrelevant information
that drowns out the relevant, yes...

I want to suggest a (slight) restructuring of our document set which I
believe will have considerable impact. (We have a meeting tomorrow. I'm
trying it out on the dog this evening. Or rather, as Keith Cronin's survey
established a slight majority, the cat.)

What we currently have:

A guide to developers, including code examples.
Release notes.
A questionnaire that the developers have to complete in full for each
service to confirm that they have designed the service as required.

What I plan to suggest, in addition:

A series of focussed tipsheets, listing the things they must not do.
A rationale to accompany the questionnaire, giving reasons (and the correct
answer) to each question.

The tipsheets will tell them what we're going to tell them.
The guide will tell them what we're telling them.
The rationale/questionnaire will tell them that we've told them what we're
telling them.

Disadvantages that I've thought of already: three documents means three
different sets of updating to do.

Advantages:

The tipsheets are intended as icing on the cake - warning people off the
truly lethal (figuratively speaking) mistakes we've discovered they tend to
think are a good idea.

The guide provides all the detailed information you could wish for, in
coherent chapters, with an index and a glossary.

The questionnaire is a given. Giving them an explanation for each question
means that we are assuming that they will want to do the right thing if they
know what it is. (The other option, as I see it, is to link each question to
the documentation, but this will also require last minute updating - they're
two separate documents, and AFAIK a self-updating hyperlink is not possible
unless we can guarantee they stay in the same directory - which we can't.)

All input welcomed.

Jane Carnall
Technical Writer, Digital Bridges, Scotland
Unless stated otherwise, these opinions are mine, and mine alone. Apologies
for the long additional sig: it is added automatically and outwith my
control.



________________________________________________________________________

E-mail is an informal method of communication and may be subject to data corruption, interception and unauthorised amendment for which Digital Bridges Ltd will accept no liability. Therefore, it will normally be inappropriate to rely on information contained on e-mail without obtaining written confirmation.

This e-mail may contain confidential and/or privileged information. If you are not the intended recipient (or have received this e-mail in error) please notify the sender immediately and destroy this e-mail. Any unauthorized copying, disclosure or distribution of the material in this e-mail is strictly forbidden.

________________________________________________________________________


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
PC Magazine gives RoboHelp Office 2002 five stars - a perfect score!
"The ultimate developer's tool for designing help systems. A product
no professional help designer should be without." Check out RoboHelp at
http://www.ehelp.com/techwr
---
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.



Follow-Ups:

References:
From Buggy-Whip to PET Scanner: From: karen_otto

Previous by Author: RE: on technical writers
Next by Author: RE: on technical writing
Previous by Thread: From Buggy-Whip to PET Scanner
Next by Thread: Re: Is there such a thing as TMI?


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


Sponsored Ads