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:Re: look & feel (warnings, notes, hints) From:John -dot- Cornellier -at- PARIS -dot- IE -dot- PHILIPS -dot- COM Date:Mon, 12 May 1997 15:59:08 +0200
Good day, eh?
Brenda Burnett "Contractor at Large" brenda -at- precise -dot- ab -dot- ca asked about formatting
for warnings, notes, & hints. Aside from the graphics issue, I'm interested in
how one defines which info is a warning, note, or hint?
IMO info is either necessary to the procedure or it isn't. In the latter case,
why not integrate it? Consider the following hypethetical but not unrealistic
example:
Using Thingy
1. From the Foo menu, choose Bar.
2. In the Bar dialog box, enable thingy....
NOTE: if you did not install the Turbo Version, the Bar option will be disabled.
TIP: access the Bar dialog box by pressing ctrl+alt+F7.
WARNING: enabling thingy will cause a Tack conflict if Colour is set to mauve.
Could be rewritten as
Using Thingy (Turbo Version only)
1. Ensure Colour not set to mauve. Mauve will cause Tack conflict.
2. From the Foo menu, choose Bar, or press ctrl+alt+F7
3. In the Bar dialog box, enable thingy.
To me the best use of this sort of marking of text is where you have users
working under different circumstances, e.g. icons to separate instructions for
different operating systems. Above could have a turbo symbol in the margin to
note a procedure for the turbo version only.
Assuming that one *is* going to use symbols or bullets to mark warnings, notes
or hints, a little standardisation goes a long way. Most people immediately
understand that a red hexagon is stop, and a yellow triangle is a warning, etc.
WARNING: these little graphics can take up big bytes.
Tip: Get a font editing program to create your own custom wingdings.
A lot depends on the product, how much leeway you've got to change the
templates, (often as a contracter not much), and the style of the docs. As it's
software user and sys/admin stuff I don't suppose Brenda'll have
anthropomorphised cartoons of files doing things. Done well that sort of thing
can be quite good at grabbing the reader's eye for a consumer product. Say, an
appliance looking depressed because it hasn't been maintained, or a dangerous
appliance scolding a child to stay away.
Yours snowmobiling the 'net,
John -dot- Cornellier -at- Paris -dot- IE -dot- philips -dot- com
TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot- Send commands
to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
Search the archives at http://www.documentation.com/ or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html
