CS99I: How to Write for the Web

Entered by Gio Wiederhold, 9 March 2002, updated 22 March 2002.

How to Write for the Web

We focus on making good textual web pages and their illustrations. There is much more to be said about highly interactive web pages.

1. Think of the reader: - this is main admonition from which everything else derives.

The reader is by default a person like you, but sometimes you want to identify the intended audience specifically.

If the audience is limited, say so politely -- "This article is intended for readers that have not had substantial experience in writing for an on-line audience".

The reader is by default a person like you, but sometimes you want to identify the audience specifically.

The reader wants to get as much actionable information as possible in a small amount of time.

The reader will get annoyed if misled by poor title, introduction, or an obsolete timeframe.

Since web material stays around for a long time, make sure to have the date in the header. Ten years later you will be less embarassed if someone quotes you.
Since the web is accessed internationally, and date conventions differ, dont use the U.S. convention MM/DD/YY, as 3/9/02 to indicate the current date. By September Europeans will misunderstand you. Instead use letters for the months, say 9Mar02, if space matters.

2. Effective organization for the browsing reader:

Meaningful and simple title, say `Review of Internet Protocols', rather than `Some Observations on the State of the Art in International Electronic Communication'.

Motivating introduction -- not so sales-ish that person will be misled into reading irrelevant stuff

Overview on the initially visible page.

Good navigation to top, to the next item, back, to overview, and to your own home page. Specify the pointers so that they will still work if the pages are moved: local HREF (="Names_of_Contributors") for closely related pages, full URL (="http:// ... ") for remote pages.

Effective and pleasant use of screen real estate: not too much white space, but not overly crowded. Be aware that there are about half as many lines on a screen than on a page; don't have more than 7±2 high level bullets.

Miller:56

Five to nine is a good guide for the number of choices in a list to be clicked, since the reader goes not need to mentally to classify the choices further.
It is also a good guide for the number of chapters in a book or the number of sections in a chapter, although when chapters or sections have a logical sequence, the reader can focus on the beginning, middle, or end of a longer list.
In business 7±2 is also a good number of people to supervise -- if there are more you are likely to loose track of some, if it's many fewer you are in an overly hierarchic organization.

Indent potentially distracting material.

In-depth material can be reached by hyperlinks. Provide easy returns to where one was (using local anchors) and to the top from any material you provide.

External references reached by hyperlinks, as in the example here for [Miller:56].

3. Useful Contents:

Identification: who wrote it, why, and when.

Self-sustaining paragraphs: since people can and will browse, help them. First sentence should make clear what paragraph is about. Related to that: don't have two topics in one paragraph.

And: don't say two things in one sentence. An annoying habit, occurring when writers are too lazy to go back and sort out their thinking, is the insertion of a sub sentence, that is a sentence that explains an uncommon noun phrase that has not occurred earlier, as being a sentence following the unexplained noun phrase, here `sub sentence', into a sentence that was intended, as here, to tell the reader not to insert such sub sentences.

Don’t refer to other material by position: i.e., do not use:

`the problem discussed above', say, when discussing shortage of capital, instead use `the problem of capital <with a clickable pointer for those that haven't read the earlier material > '.
`currently' since you don't know when stuff is going to be read, say instead `in 2002'.
the 'second point made above'
`the latter condition'
also minimize 'this' 'that', 'he', 'she', 'it' so that no mental movement is needed among contexts.

Provide value: always include in your writing some intellectual contribution of your own, typically what you think is the reason for success or failure of what you have found, and how those factors will affect what the future will bring.

4. Graphics

Pictures and symbols can make web pages more attractive, but don't overdo it.

Any pictures, graphics, background should help and be relevant, not distract.

If an object or concept appears in more than one graphic, say `the customer', use an identical icon or image.

Use color and fonts consistently. I (Gio) use, for instance, always green for databases, blue for customers, red for innovation, and yellow for research topics. Any such conventions should be followed on all other slides in the presentation. If you use a sans-serif font, also use sans-serif font when refering to the items in the text (as in the future example below).

Make the flow in a diagram follow a simple line, typically left top to right bottom, matching natural reading styles.

If you want to project optimism in the Future, make the visual flow move from the left-bottom to the right-top, by placing the content along that axis, and perhaps emphasizing that flow by placing a light arrow below the contents.

The images above are made clickable, so that a reader can get to details while still having an initial overview.
An author can also put hyperlinks into parts of images, providing visually attractive navigation. Examples on how to do that are given in the CS 99 HTML information page.

5. Reread

Since during your writing you were involved with yourself, that writing will reflect your viewpoint. When done, take a break and reread what you have written a day later, from a clean point-of-view, or have someone else read it

References

[Miller:56] George A. Miller: "The Magical Number Seven, Plus or Minus Two: Some Limits on Our Capacity for Processing Information"; The Psychological Review, March 1956, Vol.63, No.2, pages 81--97.