Patterns: Intros are optional.-- Web Writing that Works

To accommodate personal and national tastes, you may need to make any introduction into a distinct object, so it can be removed or included during customization, localization, and personalization.

An introduction may be justified if you think the user may have questions about the subject of the procedure, or the preparations needed.

What goes into an intro

As you explore your audience's skills, knowledge, attitudes, expectations, problems, and goals, you may come to see that certain questions come up fairly often, as people get ready to perform an action.

Those throat-clearing questions demand particular components in your introduction.

What is the purpose of this procedure? Goal statement
When would I do this, and why? Context
What tools do I need? Tool list
What do I have to do first? Prerequisites
Is there some key idea I need to understand before I start? Concept

You probably won't have to offer your guests every one of these components. But you should think through what exactly an introduction can do for people, and decide which of these components, if any, are really needed.

Thinking about the function of each possible element lets you discard a lot of junk.

Cut any introduction that fails its responsibility to answer at least one of these questions.

For instance, many designs require an introduction just so the name doesn't butt into the first step, visually--and so writers come up with dud intros. For instance, if the procedure is "How to return a product," then a pointless intro would be, "This procedure shows you how to return a product." Don't commit this kind of nonsense.

Resources:

Probe your audiences--gently.

Help (A chapter from Hot Text: Web Writing that Works. PDF: 995K, or about 18 minutes at 56K).

Each object in this pattern is optional. Indeed, the whole intro is optional. But if you do feel that some people might want some of these questions answered, create the intro, and allow some audiences to hide it.

If you really must write an intro

1) Follow chronological order, but don't offer actual step-by-step instructions. (You want people to follow the actual procedure, where you have a chance to offer explanations, and every step).

2) Avoid future tense, to escape timewarp. Describe what is. Don't raise the question of when. Instead of "You'll need to name the output pins," just say, "In this process, you need to name the output pins."

3) Keep the intro from overpowering the procedure. For example, move elaborate conceptual material elsewhere, leaving behind a simple definition.

4) Watch out for secret procedures buried in old introductions. If you spot one, raise it to the level of a real procedure, and put it somewhere else.

Example of cleaning out an intro

Before

Starting the Quotient System

Caution: Quotient will not launch if you have not placed a customized version of the .qinit file in your home directory. See the beginning of this chapter for details.

Invoking the Quotient System from a menu will bring you to the graphic display known as the Command Interpreter Window, but if you wanted to, you could run a SKILL routine, and bring up a non-graphic and non-interactive window; or, if you start at the command line, you can bring up the Command Interpreter Window. You'll find instructions for all three methods in the following sections.

By the way: You should already have invoked the X Window System, if it does not appear automatically, and run the QT Window Manager, if it does not appear automatically. You will find instructions for these tasks earlier in this chapter.

After

Starting Quotient

Before you start, you should already have customized the .qinit file and placed it in your home directory, as described in Customizing QInit. Quotient uses the .qinit file during startup. You only need to place this file in the home directory once; Quotient will use it from then on, whenever you start.

1. Enter UNIX and invoke the X Window System, if it does not appear automatically.

Instructions appear in the section Starting X Windows.

2. Run the QT Window Manager, if it does not appear automatically.

Instructions appear in Launching QT Window Manager.

3. Decide whether you want to use a graphics window or not.

If you want to use the graphics window, known as the Command Interpreter Window, you can start Quotient from a menu or the command line, as described in the sections Menu Launch or Command Line Launch.

If you want to use a text-only window, as in coding, you can run a SKILL routine, as described in "Starting Quotient with SKILL."

Example of deleting intros to procedures

Before

Scrolling Up or Down One Line

To scroll up or down one line at a time:

1. Click left on one of the arrows at the top or bottom of the scroll bar.

The text moves up or down one line.

Scrolling Up or Down Continuously

Here is how to scroll up or down continuously.

1. Press left on one of the arrows at the top or bottom of the scroll bar.

The text moves up or down continuously.

2. Release the mouse button when you reach the part of the file you want to see.

After

Scrolling Up or Down One Line

o Click left on one of the arrows at the top or bottom of the scroll bar.

The text moves up or down one line.

Scrolling Up or Down Continuously

1. Press left on one of the arrows at the top or bottom of the scroll bar.

The text moves up or down continuously.

2. When you reach the part of the file you want to see, release the mouse button.

Was I supposed to put shaving soap on this brush before I rubbed my face?

Web Writing that Works!
http://www.WebWritingThatWorks.com
© 1999-2004 Jonathan and Lisa Price
The Communication Circle
Discuss at HotText@yahoogroups.com
Email us directly at ThePrices@ThePrices.com
Order Hot Text (the book) from Amazon