CS73N: How to Write for the Web

Entered by Gio Wiederhold, 9 March 2002, updated 22 March 2002, 8 July 2004.

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, not `Some Observations on the State of the Art in International Electronic Communication', 'Communicating in 2004'.

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

Overview on the initial page.

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

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

This limit is related to the capacity of human short-term memory [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. 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. Be proud of being an author, but, by adding a date, readers will know that you wrote what they read perhaps a very long time ago.

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 sentence following the unexplained noun phrase. here `sub sentence', into a sentence that was intended, as here, to tell the reder you not to insert such sub sentences.

Don’t refer to other material by position, since web pages and later edits may well change the original layout : 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', pronouns as 'he', 'she', 'it' so that no mental movement is needed among contexts.

Avoid wimpy terms, words that require the reader to consider under what conditions statements are true or false: `Getting good grades may help you in the future' is a useless statement. If you mean it just say `Getting good grades helps you in the future'. Similarly, `... may be a useless statement', `War is potentially costly', `Being over 7 foot tall can be awkward', etc. You want to become an authority, and firm writing helps. If you know of exceptions, state them specifically: `Being over 7 foot tall is awkward, except when playing basketball.'.

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. Show small images, that can be expanded by clicking on them.

Any pictures, graphics, background should help and be relevant, and not distract. Use tools as Powerpoint to illustrate what you are presenting, but do not use slides initially as a substitute for careful reasoning and writing.

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

Use color and fonts consistently. For instance, I (Gio) use always green for information sources, blue for customers, red for innovation, and yellow for research topics. Any such conventions should be followed on all other images in the presentation. If you use a sans-serif font, also use sans-serif font when referring to the items in the text (as in the future example below).
Make the major flow in a diagram follow a simple line, typically from the left top corner to right bottom corners. Such a flow matches natural reading styles. creating a simple, clear layout is a lot of work.
If you want to project optimism in the Future, make the visual flow move from the left bottom cornerto the right top corner, by placing of 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. General

Exploit the capabilities of on-line documents. If possible, put all major arguments on one page and all supporting material on linked pages. make it easy to go back. Consider the shape and capacity of the screen

In scientific and commercial writing use the same term for the same item, and different terms for different items. In literary writing authors can show how erudite they are by using synonyms.

Avoid awkward approaches to be gender neutral. By avoiding pronouns the problem is reduced. Using plurals helps as well.

Be careful with collective nouns (dirt, index, salt, soap, water, work). Using them in plural form reduces them to instances: `Prior work on automated commerce' is a general statement, `Prior works on automated commerce' refers to some specific, instances, and should only be used if there is guidance for the reader that allow those works to be identified.

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

Done

If you want to go back to the 2001/2002 class notes, click .