RE: Using the STOP methodology

[Michael Hoffman <mhoffman -at- thinkshare -dot- com>]

>>Online document, for example, does not lend itself to the way in which we
transition from one topic to another in the linear model. There is no need
for transition from one topic to another; rather we are prohibited from
writing those transitions because we really don't know what transitions will
occur.


That's an extremist, crude hypertext theorist notion.  That's early 90s
extremist hypertext theory.

We know the main, default transition is from one topic to the next, as
defined by the TOC.  We are not prohibited from writing the transitions.
However, in my "linear hypertext" paradigm, I would stop short of writing
"As we have seen above..." -- but then, I would never write that in a
print-only document, either.  I don't read print books literally from cover
to cover.  To present info linearly does not imply that it is literally read
from start to finish.


>Couldn't either of these two types of documentation make use of the same,
effective transitions, and aviod the worse?

Yes, whether print-only, online-only, or print-and-online, I would write the
same way.  I would not say "As we saw above...", but rather, "As shown in
the foo section above, ..."

I have no objection to saying "see below" or "see the next topic" online.  I
don't buy into the radical break idea separating topics by a great divide.
I consider adjacent topics to flow from one to the next.  The great divide
is just a thin illusion that we should downplay.  Hypertext still provides a
linear main browse sequence, though scrolling-ranges have endpoints and you
have to do an action to jump from one topic to the next, closely related
topic.



>Isn't part of the current thought about online documentation that the
writer has to present the topics in a way that will lead the reader to the
next best topic?

Yes, the TOC should be considered by author and user as defining a main
default reading sequence.  It is a hellish assumption that was introduced in
the mid-90s that, in the name of "freedom" and "hypertextuality", there is
no default sequence.  That way lies madness and schizophrenic
disorganization, of which we saw the fruit around 1999, hopefully the point
of greatest chaos and least orderly structure (it was a great year for
printed computer manuals).


>Or is there a bigger distinction that you see between transition types,
than between these two examples:
"For more information about downloading the file to your computer, see
"Downloading the file to my computer" (on page xx <for print>).".
"For more information about downloading the file to your computer, see
below."


If the destination topic is far away, I'd write:
Print:
For more information about downloading the file to your computer, see
"Downloading the file" on page 123.

Online:
For more information about downloading the file to your computer, see
_Downloading the file_.

A main purpose of a HAT is to take care of page number updates and link
construction to flip between these two forms.


If the destination topic is near, I'd write:
Print:
(nothing)

Online:
(nothing)


Some authors are committing a great communication crime: they are "helping"
the user by omitting topics from the TOC, so that you arrive at a topic and
the TOC cursor goes gray, so where are you in hyperspace?  Nowhere; you are
Lost In Hyperspace.  So here I must point out that in print I expect every
topic to be listed in the chapter TOC or detailed TOC, and online I expect
every topic to be listed in the TOC.  This should be a shared assumption of
the author and user.  No wonder we have the doubtful notion that "users
don't use the TOC", if the TOC is so poor that half the topics aren't even
listed in it.


It is not very necessary to *explicitly* tell them that the adjacent topic
is closely related.  *Of course* the adjacent (in the TOC) topic is closely
related, or else it wouldn't be adjacent (this is generally true).

Hypertext authors have been shooting themselves in the foot by denigrating
conventional printed-document linear structures, so now the audience has
abandoned the assumption that adjacent topics are probably related and if
you like one topic, you probably want to skim its siblings too, at least in
the TOC.

Authors and the audience should both resume the classic assumption that
related sections/headings *tend* to be grouped together.  Imagine a book
with subheadings/subsections, where at the end of each subsection you say,
"Next, we recommend that you read the topic, foo (shown in the next
subsection)."  I expect readers to be constantly clicking the Contents tab
to explore or skim the adjacent headings.  That is the golden path I wish
authors and audience would all assume:

1. Use direct-entry to get into the Help -- such as F1, Search, or Index.  A
topic appears.
2. Before even reading the topic, click the Contents tab (Sync TOC should
highlight the current topic) and skim the neighboring topics to see if
there's an obviously better topic nearby.

So it may be true that users *initially* enter help through Index/Search/F1
rather than Contents.  However, it is essential that the Contents is used to
follow-up the first action, particularly for conceptual topics.  Authors
should resume carefully crafting the TOC, and the audience should resume
relying on the TOC after doing a Search.  

The TOC was never intended to compete against Index/Search as though you
would only use one during this session, and another during that session.
Rather, the user would always use multiple navigation approaches *in
conjunction*.  This saves the author from the labor of linking to the
subsequent topic -- let that connection be traversed through the user using
the TOC intelligently.  

That should be a shared expectation and convention between authors and
users.  It is actually confusing to me if there is a hypertext jump that
merely leads to the next topic.  Much of this design potential relies on
setting up a shared paradigm.  If authors entirely lose faith in the
Contents, they produce unusable or no Contents, and of course then the users
don't use Contents, and need bucketloads of links instead, until the whole
thing becomes a mind-boggling mess of links with no distinction between near
and far links.  

Links to the next topic imply globally reproducing, *manually*, the entire
TOC within the body of the topics -- that idealist over-linking approach is
impossible to maintain, and presents a great barrier to improving the doc by
restructuring.

By convention we should link to far links only, rather than putting a link
to the parent topic and the next sibling topic.  I've seen, in VC docs, what
happens otherwise: insane link-mania, it's crazy and assures the sales of
many more printed manuals.

Let any writer who thinks hypertext conventions are optimized be chastened
and sobered by the great popularity of printed computer books.  I think
online docs don't have a chance until they do everything possible to act
like a well-designed printed computer book, in addition to having features
unique to online.

-- Michael Hoffman
hypertextnavigation.com

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

A landmark hotel, one of America's most beautiful cities, and 
three and a half days of immersion in the state of the art:
IPCC 01, Oct. 24-27 in Santa Fe.  http://ieeepcs.org/2001/

  +++  Miramo -- Database/XML publishing automation.  See us at  +++
  +++  Seybold SFO, Sept. 25-27, in the Adobe Partners Pavilion  +++
  +++ More info: http://www.axialinfo.com  http://www.miramo.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.