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.
-----Gene Kim-Eng wrote:-----
In this situation, I would make the caution part of the step, i.e.,
when you click on the link to the step, the caution should be at
the top of the page/frame/whatever that contains the step, prior
to the text of the step itself.
-----------------------------
Gene, I agree wholeheartedly with both you and Eric Dunn. I just wanted to point out that this hyperlink issue is a design consideration for a document that will exist electronically in PDF or HTML (don't know how XML would handle it). You can't place a caution before a step without making sure that any hyperlinks take you to the caution so the user can see it before completing the step--assuming that the user would see the caution at all otherwise. That could get you into legal trouble as well.
My preference is to do as you said--to make the caution a part of the step. Step numbers are a logical divider between steps, so I don't think it's logical to place cautions before the step numbers. Doing that makes it hard to distinguish between the supporting information in the prior step and the so-important-that-you-have-to-read-it caution that goes with the next step. However, cautionary text should come before the instructions in the step rather than after so the user sees it before doing something that can't be undone.
The easiest way that I can think of for taking all of this into account is to put the procedure in a table with each step as a separate row. The first column could contain the step number and the second all of the text, including any notes or cautions in a logical order (caution first, instructions second, supporting text last). Whether or not the table had lines or shading would be a matter of style. It could have none and still be effective. Something to the effect of:
-------------------------------------------------------
1. ! CAUTION - Do not look directly into the laser beam.
Position the laser...
-------------------------------------------------------
2. Next instruction.
-------------------------------------------------------
This may look a little odd from what most of us are used to seeing, but I think it's effective. I'm working in Frame, but this could apply to other programs. Does anyone have any other ideas for how something like this could be implemented? Could it be done easily without a table? (The key word is *easily*.) Right now, we occasionally create cross-references to the step numbers ("Repeat step 5." OR "Continue with step 3.") Creating the cross-reference to a caution above a step wouldn't bring in the step number. I'd prefer to avoid awkward wording such as "Repeat the step where you had to..."
Just trying to get the creative juices flowing. :-)
ROBOHELP X5: Featuring Word 2003 support, Content Management, Multi-Author
support, PDF and XML support and much more!
TRY IT TODAY at http://www.macromedia.com/go/techwrl
WEBWORKS FINALDRAFT: New! Document review system for Word and FrameMaker
authors. Automatic browser-based drafts with unlimited reviewers. Full
online discussions -- no Web server needed! http://www.webworks.com/techwr-l
---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- techwr-l -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.techwr-l.com/techwhirl/ for more resources and info.
