TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:conventions From:John Prince <prince1 -at- WEBTV -dot- NET> Date:Sat, 30 May 1998 10:10:45 -0500
I completely agree with writing a "Conventions Used in this Book"
In fact, I also include a "Dialog Box Elements" section, which explains
each of the elements that appear on the various dialogs . . . and how to
use them, such as spin boxes, drop-down list boxes, option buttons, etc.
I have found this useful. For example, you write: "Use the up and down
arrows in the Date spin box to select a value. You may also highlight
the default value and type a valid value." The reader may not know what
a spin box is.
Also, as for functionality, it certainly doesn't help to let the readers
know what the limits are for each element.
Some may feel it's not "chic" in the TW world to do so, but my main
concern is the reader, and the usability of both the product and the
I think that even a basic user who is confused at what bold text means
might look in the index under "bold text" and find that it represents
commands and dialog box names.
I understand that most users probably don't read these sections. But I
that shouldn't take away the opportunity to read it if so desired should
My feelings are that any bit of confusion that can be eliminated should