Editing and publishing
Once the main text has been written,
you edit it. Editing means
breaking text into sub-documents;
pointing out connections to
other texts; making sure the document as a whole is
in good shape; adding indices and outlines.
Editing doesn't necessarily happen after the first
text has been written - I mix those stages all the time -
but it deserves to be thought of as an independent
discipline, because the problems it deals with are
Most of what people
do on the World Wide Web is really editing,
Navigating in the World-Wide Web takes too much time to
it distracts from the contents of the subtree.
That is only a technical limitation of the system, not
a conceptual one; there is nothing specific to hypertext
documents that makes them harder to navigate than linear
Nonetheless, you must take this distraction into account
when you organize your document; you are writing for real
people in a real world, not for the unlimited-bandwidth
user of the future.
If you feel compelled to split your text in easily
digestible single-page chunks, keep in mind that there will
be breaks between them.
If your information bears that kind of segmentation - if,
for example, you're presenting small lessons of a tutorial -
the pauses are beneficial;
they help your students to relax and give them the feeling of
having accomplished something.
But if you're just trying to entertain or convince, you would like
your document to have an overall rhythm or flow that captures the
reader's attention while not distracting from what you have to
latency of the World Wide Web means that you will have to provide
this rhythm using conventional means like typography and layout;
not through the hypertext structure.
Respect throughput and connectivity.
There is such a thing as a "too large" document.
Beyond what size documents are too large depends on the location
and material conditions of your audience, the bandwidth of
your site's connection, and the browsers you expect your audience to
use. (If you must have an estimate,
anything above 30 K makes me
queasy, and I frequently see international transfers of my
own larger documents aborted.)
If you cannot, or do not want to, break a document into smaller
parts, the links to it must carry the weight: the longer the
data takes to download, the more important it is not to disappoint
the readers. (Consider annotating the links with
the size and format of the target document.)
If you are serving formats other than HTML, familiarize yourself
with the compression techniques your server supports, and consider
offering smaller, low-quality samples before the user
downloads the complete, high-quality document.
Plan for search engines.
There are search engines (sometimes called "robots,"
"crawlers," or "worms") that traverse
the World Wide Web, compile indices of the documents
found there, and then let other users search these
indices for keywords, returning the URLs of
documents matching one or more search patterns.
This kind of service is tremendously helpful -
and completely unnerving, because its attention span
is just below Beavis and Butthead's. It
subverts any hierarchical structure or learning
curve you might have
planned for your pages (people have never read your
introduction); and it listens only to words, not to
Once the WebCrawler has visited
your essay about
the naked incomprehension greeting a women's group's
demand for censorship of pornographic newsgroups,
the vast majority of its
visitors will have been searching for "porn,"
"naked," and "women."
Documents as a whole can escape traversal by being
listed in a file "robots.txt" in a site's toplevel
directory. If you choose to be indexed by
the search engine,
allow for some degree of disorientation among your
visitors: they didn't necessarily enter through the front door.
Look around you.
Before you become a resource for a subject,
take an evening's time to familiarize yourself with
what has already been written about it on the web.
This takes courage: you may learn that the
project you were about to embark on has already been
finished - perhaps slightly worse than you would have
done, but not bad enough to be worth repeating; or
much more graphically attractive than you can hope
to make it, but with inane texts; or just so highly
publicized that you don't stand a chance to compete.
Still, inform yourself. Don't treat your
readers as if your site was the only one they knew, and
don't treat other writers and designers as if they didn't
(And of course you might also run into someone who
has done interesting work on a related area,
doesn't mind sharing it, can tell you something new about
writing, and still laughs about your jokes even after
you've been married for ten years.)
Don't recommend a resource just because it exists.
If you are treating a subject, and another page that
purports to deal with the subject doesn't satisfy you, explain
Don't let yourself be bribed into merely
reciprocating links, either; there are dozens of
sites that will unconditionally link to your page
if you link to them. Yawn.
Given an anchor and the surrounding context, your readers
have certain expectations as to where the link will
If your target cannot match these expectations, change the
text, or lose the link.
Choose durable filenames.
The filename of the hypertext document will become part of
the Uniform Resource Locator (URL) that people use to address
In an ideal world, URLs would not matter and would never
be seen by people; in reality, they are published, quoted,
and seen by the users when they access your pages.
Before you publish a page, make sure that the filename
you have chosen, when seen out of context, represents the contents
of the documents, and will continue to do so a few
Think early about opening new subdirectories.
If your paper has an illustration and a couple of footnotes,
move it into its own directory. When you start,
having nothing but one or two subdirectories below your
toplevel page seems pathetic; but as you continue writing,
you'll be glad to have kept last month's clutter out of the way.
Time your entry.
Unfinished pages are the bane of hypertext writing. While
few writers have the courage to let others see unfinished linear text,
it seems to be common practice among users of the World Wide
Web to create
an intricate structure of yet-to-be-filled pages
with just links to each other, a fancy image of a building site
or street sign, the words
This page is still under construction. Please
and at least three <hr> lines to separate one from
the other. (In these modern times, there are even
"home page generators" that allow people to produce even larger
pieces of meaningless cruft with nothing but the press of a button.)
Don't add your own litter to the junkheap. If
you have unfinished hypertext, fine, don't link to it; your hypertext
browser has an option (most likely simply the URL as the command
line argument) to let you view hypertext even if you can't
get to it from your organization's home page.
If your page is meaningful enough to be enjoyable, yet still under
construction in the sense that you anticipate making changes
to it, don't apologize for it, just do it. It is
perfectly normal to change hypertext; most informative documents
will change with time as more information is added to
it. If you want to give some indication that
the page is changing, attach a "Last modification"-date
Keep your mind in your head.
Announcements about the future are appropriate for scheduled
events that your readers can participate in - concerts, conferences,
broadcastings, requests for material -, but simply dumping your
personal stream of consciousness into an otherwise factual
page is rude. As in the case of
"click here"-notes, the
readers are torn from their interest
and directed to the administrative aspects of hypertext at
a time they can't control.
Many readers are genuinely curious about the development
in a subtree; I routinely choose the "What's New" page of a site
I visit for the second or later time. If you can't
suppress the desire to write about what's planned, rather than
what's done, consider writing an "Upcoming Events" page that
assembles all your plans into one document.
If you do that, make sure you maintain that page at least as
well as the rest of your site - when you change your mind in
your head, change your mind on the page as well.
Spell-check your text.
If your authoring environment does not include a
spell checker, save your document in ASCII-only
format from a hypertext browser, then run it through a
regular spell checker. ("lynx -dump url
is a good first try on a Unix system.)
Any and every document that you offer to an audience should
be spell-checked as a matter of course.
Electronic spell-checking cannot substitute for the
diligence of human proofreaders and copy editors; it
is merely one stage in the long, tedious process of
saying what you want as clearly as possible.