Re: Reading levels?

[Stuart Burnfield <slb -at- FS -dot- COM -dot- AU>]

Misti (ncr02!mdelaney -at- attmail -dot- com) said:
> My understanding (going *way* back to my college classes on readability) is
> that any technical word necessary to the subject matter, once defined and if
> used consistently, is acceptable in 8th grade reading level.

This makes sense, but you need to be sure that the reader will have seen
the definition by the time they first see the term used. Manuals are
rarely read from cover to cover. On-line help doesn't _have_ covers.

Perhaps the manual could start with a 'Read This First' that tells the
reader to look in the glossary or overview to find out the meaning of
specialist terms. On-line manuals could pop up a definition when the
reader clicks on a key phrase, a la WinHelp.

Back to Brett's original question: I suggest you read up on 'Controlled
English'. Documentation written using CE features:

- a limited common vocabulary (approx 300 - 350 words)
- an additional specialised vocabulary containing special terms, product
  & tool names, etc)
- a dictionary defining all the words in the vocabularies

(There's more but I think this is the bit that applies to Brett's query.)

CE was originally developed to make translation much simpler, and for
use by people for whom English wasn't their first language. However it's
meant to make manuals more useful for English speakers, too.

If you can get hold of someone's common vocabulary, this will give you a
head start on deciding which of your words need further definition (your
'specialised vocabulary').

One warning: there may be some words that would normally be considered
OK for your 8th grade readers, but should still go in your list of
defined words because they have a special meaning separate from the
common meaning -- e.g. program, default, disable, enter have special
meanings in the software world that are different from their everyday
meanings.

I read about Controlled English in

'Writing Better Computer User Documentation' by R. John Brockmann
John Wiley & Sons 1990 ISBN 0-471-62260-5i -- see page 112 -113.

He refers to a paper by Gayle Gustafsen, "Controlled English for
International Audiences"

This is my second reference to the Brockmann book in two days! It's a
good one -- I recommend it.

Regards
---
Stuart Burnfield (slb -at- fs -dot- com -dot- au)        Voice: +61 9 328 8288
Functional Software                     Fax:   +61 9 328 8616
PO Box 192
Leederville, Western Australia, 6903