What is...? Text Editing Maintenance Words Related Material

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 different. Most of what people do on the World Wide Web is really editing, not writing.

Respect latency.

Navigating in the World-Wide Web takes too much time to pass unnoticed; 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 text. 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 say. The 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 arguments. 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 exist. (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.)

Discriminate.

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 why. 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.

Be accurate.

Given an anchor and the surrounding context, your readers have certain expectations as to where the link will point. 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 it. 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 months hence.

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

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 to it.

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 | spell" 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.

What is...? Text Editing Maintenance Words Related Material