CS73N: How to Write for the Web
Entered by Gio Wiederhold, 9 March 2002, updated 22 March 2002, 8 July 2004, 25 March 2005.
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 for your material limited, say so politely and early -- "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: "This article will help you if you want to write instructional web material".
The reader wants to get as much actionable information as possible in a small amount of time. The reader's time has value!
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
2. Effective organization for the browsing reader:
Meaningful and simple title, not `Some Observations on the State of the Art in International Electronic Communication', say 'Communicating in 2005'.
Motivating introduction -- not so sales-ish that a person will be misled into reading irrelevant stuff
Overview on the initial, visible page, i.e., about 20 lines.
It's on-line, so provide 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. In depth material can be reached by hyperlinks. Provide easy returns to the spot where the reader was earlier (using local anchors and to the top from any material you provide, or add the magic target="_blank" to the HREF to bring the page up in a new window, as described in <A HREF= "http://www-db.stanford.edu/pub/gio/CS99I/html-inf.html" target="_blank">HTML description</A>.
Effective and pleasant use of screen real estate: don't use to much white space, but not crowd the material either. Be aware that there are about half as many lines on a screen versus a printed page.
Making points is effective, but 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, or just provide a remote link to it.
External references are always reached by hyperlinks, as in the example here for [Miller:56].
3. Useful Contents:
1. Again: 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.
2. 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, which I call here a `sub sentence', into a sentence that was intended, as here, to tell the reader that you should not to insert such sub sentences.
3. 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, just repeat `a shortage of capital <with a clickable pointer for those that haven't read the earlier material> '.
- 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. Be explicit: `the creator (of the web page)'; even though you might have been taught to avoid repetition in linear writing.
- `currently' since you don't know when your writing is going to be read, say instead `in 2006';
- `at the time this is being written'; the reader should not need to care about your time frame.
4. Avoid wimpy terms, words that require the reader to consider under what
conditions statements you make 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'.
5. 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 create slides initially as a substitute for careful reasoning and writing.
If an object or concept appears in more than one graphic, say `the customer', use an identical icon or image for all occurrances.
|
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. Be aware that 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 corner
to 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
7. 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 
.