As explained in the next section?

Subject: As explained in the next section?
From: "Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Wed, 11 Apr 2001 11:46:13 -0400

Harry Hager wonders about <<the use of the phrase "as explained in the next
section" in user manuals, both print user manuals and online help.>>

I'm of two minds about this; provided the sequence is indeed linear, and
that the next section really must be _the next section_, then it's probably
not inherently evil. The main problem is that it's not precise; in my
experience, readers have taken "section" to mean anything from the next
chapter to the next subheading in the current topic. Really! The secondary
problem is that when you move the phrase online, it doesn't communicate well
because the next section may not be visible onscreen, and someone may well
jump to another seemingly related topic before they ever see the actual next
section.

<<Here's an example where the phrase might be used: The program opens the
ABC window. The information you enter in this window, as explained in the
next section, makes up the search criteria for your XYZ query.>>

My initial suspicion is that there shouldn't be a "next section", and that
the details should be part of the explanation, but I'd have to see the full
context to come up with a more definite verdict. One trick I use for all
such topics is to provide a mini-table of contents (TOC) at the start of any
long topic (more than a couple screens), with each of the headings in that
topic accessible via a hyperlink in the mini-TOC. To me, this provides both
fast access to points later in the topic, and an overview (schema) of the
topic so readers know what follows. For example, in your case, this might
be:

Querying the data warehouse
Opening the window
Entering data in the window
Closing the window
(followed by the first heading and the text it introduces; the indented
phrases are links to matching headings).

<<I'd like to know what you all think about the use of this phrase for
material that is going to be online help. With regard to this phrase, is
online help different from printed text?>>

Online help really is different in this case. The really nice thing about
online help is that you can provide a hyperlink directly to the correct
section, thereby eliminating any ambiguity about what section you really
mean. In your case, this might look something like: "Now that you've opened
the ABC window, you can _define the parameters of your query_." (The _..._
indicates the underlined link, which goes directly to "the next section".
With a bit of editing, you could certainly come up with something more
elegant and with a shorter hyperlink so the page isn't infested with long
underlines.)

<<What about the repeated use of this phrase in online help? How soon would
the reader get tired of seeing this phrase?>>

They'd probably get tired equally fast in text and online. It's like any
form of repetition: after a while, it begins to draw attention to itself and
away from the topic.

--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca
"User's advocate" online monthly at
www.raycomm.com/techwhirl/usersadvocate.html

"The most likely way for the world to be destroyed, most experts agree, is
by accident. That's where we come in; we're computer professionals. We cause
accidents."-- Nathaniel Borenstein

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available 4/30/01 at http://www.devahelp.com or info -at- devahelp -dot- com

Sponsored by DigiPub Solutions Corp, producers of PDF 2001 Conference East,
June 4-6, Baltimore, MD. Now covering Acrobat 5. Early registration deadline
April 27. http://www.pdfconference.com.

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit
http://www.raycomm.com/techwhirl/ for more resources and info.


Previous by Author: Picking nits?
Next by Author: The demise of the printed manual?
Previous by Thread: RE: As explained in the next section?
Next by Thread: RE: As explained in the next section?


What this post helpful? Share it with friends and colleagues:


Sponsored Ads