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: Another Newbie question about procedures From:mearro -at- msn -dot- com To:"TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com> Date:Tue, 17 May 2005 16:57:16 -0600
John:
In my message, I didn't mention printing a report but printing a
confirmation message (the screen that displays after the task was
completed). I don't think many docs include a separate topic on how or why
to print a confirmation message.
My point (or the point that I intended ;) was that this is information
that is not an actual step in the procedure but that (in certain
circumstances) could be useful to a user who completes the procedure. And
in this instance, it's information that is unlikely to be covered
elsewhere.
Anyhow, my reason as a longtime lurker for joining in on this discussion
was to express my distaste for the following type of procedural info (a
variant of which was recommended to a newbie writer):
7) To complete XYZ procedure, click OK, or to not complete XYZ procedure,
click Cancel.
What's my problem with this step? Well, the second part of this step is
completely unnecessary & what I would consider needlessly confusing.
Instructions should address how to complete a procedure - not how *not* to
complete the procedure.
Some other types of procedural steps I can't stand:
3) The XYZ screen displays.
[What is the user supposed to do here? This isn't a step - there's no user
action.]
5) Enter the user name.
6) Or search the database and select the user name.
[Either/or actions should be one step - users aren't going to follow both
of these steps.]
9) Enter the user address in the XYZ field and select the privileges
associated with the user in the Privileges area of the Users Are Us
window.
[If it's two steps - write it as two steps.]
Mary
John Posada wrote:
> Here's where I see the problem with this. The topic title is
> "Request a Report". If I want to know how to print a report, I'd
> never think of looking here. On the other hand, if you place how to
> print the report in this topic, and you also have a separate topic on
> "Print a report" and the process changes, you now have two places to
> maintain.
>From my previous message:
> > I write the topic "Request a report." In this process, after the
> > report is requested, a confirmation message displays with request
> > details. I include numbered steps detailing the process up to
> > this point. After these steps, I include a note stating: To print
> > details of your request, click Print. I add a brief explanation
> > of why the user would want to print these details.
New from Quadralay Corporation: WebWorks ePublisher Pro!
Completely XML-based online publishing. Easily create 14 online formats, including 6 Help systems, in a streamlined project-based workflow. Word version ships in June, FrameMaker version ships in July. Sign up for a live, online demo! 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 lisa -at- techwr-l -dot- com -dot- Visit http://www.techwr-l.com/techwhirl/ for more resources and info.
