Order Out of Chaos
The Beauty of Hyperlinked Documents
(and the Future of Computer Books)
(This document last revised May 18, 1997)
Copyright 1997.
Bruce A. Epstein. All Rights Reserved.
"The news of my death has been greatly exaggerated."
-- Mark Twain, speaking on behalf of books
"You're out of order! You're out of order! The whole system's out of
order!"
-- Al Pacino in "...And Justice for All", speaking to the World
Wide Web
"If the medium is the message, choose the right medium."
-- Bruce Epstein speaking on behalf of Hypertext
With web-based content growing like kudzu, why haven't computer books gone
digital? Ironically, to date, the web has prolonged the preeminence
of printed books. Amazon.com and other
web-based bookstores have made it easier to obtain books, while the slop
permeating the web has probably increased resistance to other electronic
publications. Users are retreating from the chaos of the web to the comfort
of dead-tree tomes, just as software publishers are phasing out printed
manuals.
At their September 1996 Users Conference, Macromedia
proposed offering documentation solely via their web site, and not shipping
printed or electronic, documentation. The consensus (as indicated
by the audible gasps) was, "You've got to be kidding!" Only nine
months later, the on-line approach appears substantially less insane. It
will be feasible once the web is accessible to all computer users.
Even though printed books' days may be numbered in the thousands, they are
numbered nonetheless. Inertia will give way to superior electronic documentation
as publishers determine how to get paid for on-line information and authors
master the new medium. The web currently represents chaotic access to
anarchistic information. By providing integrated access
to structured information, authors can exploit the strengths
of hypertext while avoiding the common pitfalls on the web. Content providers
who fail to adapt will watch their profits dwindle, even as the information
market booms.
Like all authors, I have a desire to both inform and impress the readership
at large. I wanted to write a book about Macromedia
Director (the dominant multimedia authoring tool), and struggled to
develop a satisfactory approach. Multimedia encompasses several disciplines,
each one deserving in-depth coverage. But information vital to some readers
is of no interest to others, and the typical multimedian has no time for
thousand-page books. I decided to publish some of the material on my
web site instead. Organizational issues that vexed me for months simply
disappeared once the material was liberated from the static and linear confines
of a printed book.
HTML-based publications have numerous major advantages:
- Electronic searches are possible (however, a search mechanism is no
substitute for a well organized and linked site.)
- The "index" is embodied in the hyperlinks themselves and
is therefore tightly integrated with the text.
- There is no need to duplicate information available elsewhere on the
web. Simply focus on your value-added content and link to other URLs where
appropriate.
- Because printing and distribution costs are zero, publications can
be modified frequently to fix errors, improve coverage, or keep pace with
software changes and bug reports (and there is never any returned stock.)
- You can link to non-textual media such as examples, graphics, e-mail,
animations, sounds and video
Mastering your Domain
My web site's primary purpose is to sell my utilities, but it is laden with
information for Director developers. By demonstrating how my products address
common problems, the site can reconcile my goal (selling software), with
the user's (solving their problems). The site also answers pre-sales and
technical support questions, reducing phone calls substantially while increasing
sales. Even if readers do not make an immediate purchase, they will return
frequently, and refer others to my site.
The foundations of my site are the glossary
(which also serves as an index), the library
of technical notes, and a series of FAQs.
The remainder is information about my products,
including complete documentation
in HTML format, which refers to the glossary and technical notes frequently.
The goal is to create a publication that adapts to the reader's skill level
and learning style. No more agonizing over the appropriate depth or order
of coverage! I actually cover more material than I otherwise would in-line,
and yet the user can read it faster, as they choose which links to
skip or pursue.
A useful electronic publication should have a definite structure, and a
starting point, such as an FAQ or table of contents. My Needs
Analysis FAQ quickly directs the user towards solutions to common problems.
My eventual goal is to build a cross between an expert system and a reverse
dictionary. The user will peruse a list of topics or questions, and follow
the links to a solution.
When designing a site or other electronic publication, bear in mind:
- The publication should have a definite hierarchy, allowing the user
to find what they want within three clicks.
- Plan your framework by constructing outlines and prototypes, and by
examining other sites. It is difficult to reconfigure a site, so plan carefully,
and consider a tool, such as Microsoft Front Page, which will update links
automatically when a page moves.
- Divide documents exceeding five screens worth of material. For example,
I divided the glossary into separate pages for each letter of the alphabet.
- Provide easy access to a starting point for your electronic publication.
The footer of every page on my site links to the Table
of Contents, TechNotes,
FAQs, Glossary,
Download Center, and
Product Information
pages.
- Use hyperlinks to clarify items that would ordinarily appear in an
appendix, glossary, sidebar or technical note, but avoid the temptation
to make everything a hyperlink. A page should contain a complete
account of the primary topic.
- In an FAQ,
answer the question briefly before referring the user elsewhere for details,
such as:
Q. Are your products royalty-free?
A. Yes our products are royalty-free, as described in detail in our
licensing FAQ.
- Someone intimately familiar with the content should create
hyperlinks as the publication is built. As you use new concepts or terms,
add them to the glossary rather than explaining them in-line. As you encounter
peripheral issues, create a technical note that explains them in more detail.
- Broken links unnerve people. If necessary create a placeholder page
that says "This page under construction. Please check back soon."
Some site management software will verify your links. My ISP provides a
list of broken links that I attempt to fix immediately. Some servers allow
you to create a "catch-all" page that is displayed whenever a
broken link is encountered (rather than simply generating a 404 "File
not Found" error.)
- Use hyperlinks extensively, but not excessively. Whereas
my Table of Contents is entirely hyperlinks, and the FAQs have numerous
links, I use fewer links as I funnel the user's attention towards the information
they seek. This allows the reader to take detours at their leisure, but
provides closure at the most detailed level.
- Hyperlinks are no substitute for useful content and quality editing.
IMHO, the low
acceptance of existing electronic publications is due to their poor quality.
If your HTML editor does not have a spell checker, check the text in a separate
word processor.
- Each browser renders HTML differently, so test your publication in
a variety of browsers under both Macintosh and Windows. My site makes minimal
use of features such as tables and frames, which are not supported by all
browsers. Adobe
Acrobat PDF
files are an alternative for creating hyperlinked publications. Acrobat
maintains precise control over the layout and appearance of a page, and
the Acrobat Reader is free from Adobe.
Some browsers support PDF files within an HTML page, so you can mix and
match the two.
- Hyperlinks are automatically hilighted by the user's browser, so avoid
pointing them out with the phrase "Click Here." Don't spell out
URLs or e-mail addresses contained within a hyperlink. Structure your sentences
to include the hyperlink naturally.
Wrong:
Click here to visit Ellipsys International Publications at http://www.ellipsys.com
where you will find pictures of Nan McCarthy in a pink chiffon dress, or
e-mail Nan at nan@rainwater.com
Right:
Visit Ellipsys International Publications
to see the lovely Nan McCarthy modeling
a pink chiffon dress.
After several months of occasionally diligent work, the foundation of my
site is now firmly in place. Many basic technical notes have been completed,
and the glossary is almost done. Information about the company, licensing,
ordering, and product pricing is in place. Most of my product manuals have
been converted to HTML format, and I can easily add new features, product
descriptions, examples, technical notes and FAQs atop the existing foundation.
I am ready to begin publicizing my site via other sites, discussion groups
and a company mailing
list.
During a recent tech support call, I proudly referred the customer to the
new site, and asked if they had read the HTML documentation. "I'll
read it as soon as I print it out," he replied. Maybe Mark Twain was
right.
-- Bruce A. Epstein
Home (Spotlight) | Table
of Contents | Links | Contact
Info
Place an Order | Products
for Sale | Licensing | Downloads
TechNotes | FAQs
| E-Mail Zeus | GuestBook
| Glossary
![[End of Page]](../images/zeop.gif)
Copyright 1997.
Bruce A. Epstein. All Rights Reserved.