CS73N: How to Write for the Web

Entered by Gio Wiederhold, 9 March 2002, updated 22 March 2002, 8 July 2004, 25 March 2005, 18 March, 25 April, 19 July 2006.  Notes on 24 April 2008 Wired Moon talk on the subject of how to write for the web and how to design more understandable web pages.

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 the 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 for your material is 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".

You should also state the objective early on: "Reading 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 likeley came to your pages by browsing, not by knowing that your page has the desired information. That reader will get annoyed if misled by poor a title, vague 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.
• Have your name on it, and some way to locate you, so you can get feedback and improve your work.
• 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. and think you meant 3.9.02, the third of September in one of their common notations. Another convention seen is 03.09.02, a sortable notation indicating the second day of September 2003.  What to do?  Use letters for the months as I do throughout, and full years: 9 March 2002. You can use 9Mar02, if space matters.
• Since your readers can be anywhere in the world, do not use terms as `local', `nearby' or even `far away', if you have not established the locale of your setting unambigously.   You reader may be in that far way place.

2. Effective organization for the browsing reader:

Compose a meaningful and simple title, not `Some Observations on the Current 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.

In general, avoid hyperbole. You don't have to say `This very famous actor'. If that actor is really famous, the reader will know that, and if the reader doesn't know the actor, the reader is being slighted as being unknowledgeable. 

Make sure that the overview fits on the initial, visible page, i.e., is less than about 20 lines.

Since your work is 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 xhref= "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 does not need to mentally 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], which is the reference for the number of choices in a list or bullets in a presentation slide.

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.  Don't have two topics in one paragraph.

The first sentence should make clear what paragraph is about.  It should not be negative, but induce people to read more.  a nice example, cited by a friend, is the first sentence of a 4289 page book, which certainly requires motivation to pick up.  Any ifs and buts and althoughs, that would tend to waeken the impact of that sentence, can be dealt with later in te paragraph.

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'. When discussing shortage of capital, just repeat `a shortage of capital -- with a clickable pointer for those that haven't read the earlier material and need a precise defintion of capital -- '.
• the 'first point made above'.  Same problem, just respecify the point, now definite: `The shortage of capital'. Self-sustaining paragraphs  may be longer, but read faster.
• `the latter condition'. Same problem, just say: Being able to read material fast not only saves time. it makes the reader more confident.
• 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';, or``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, phrases as  `... may be a useless statement', `War is potentially costly', `Being over 7 foot tall can be awkward', etc., should be avoided. 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 in the image, also use sans-serif font when referring to those items within the text, as in the `Future' example below.	Click on picture to see full size version
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. You can use some public clipart or icons, but do so sparingly.	Click on picture to see full size version
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. Here I created my own clipart, as the for analysts and the pointy-haired boss.	Click on picture to see full size version

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 show how erudite they are by using synonyms.  The web reader cares about content, not you.

Avoid awkward approaches to be gender neutral. When a reader encounters them, he/she is distracted by politcal correctness from your message. 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.

Footnotes have no place when writing for the web. Use clickable remote entries for all references and explanations.

Avoid parenthetical (often asides for insiders) expressions. They amount to an insult for the outsider, who does not understand them.  Most webbrowsers are likely outsiders.  If the note is valuable to all, make it complete, but indented paragraph. If the note is of value mainly to insiders, say so and make it available via link.  If there are many, have an entire web page for insiders, with anchors so the reader gets to the right spot, and have an easy way to return to the main text.  

6. Tone

Write with conviction, authority, direct. Assume the reader is interested in the contents, not in you.

"I believe that most people will have mobile access in 5 years"  --> "Most people will have mobile access in 5 years"

"Global warming may affect hurricane strength" doesn't convey anything. --> "Global warming affects hurricane strength [ref]"  You could then quote some authorities that disagree -- if that is what you believe or want to make clear. But do not start wimpy.

Avoid parenthetical expressions. They either (in many cases) convey uncertainty or address an in-group audience (as this class). After updating how to write for the web I did find an instance in Science "The peaks of the electromagnetic radiation are separated by about 2 femtoseconds (a femtosecond is 2^-15 seconds)." Is that use okay?

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

8. References

Make references clickable, without taking the reader away from the page.  Include the author's name in the reference, so that a knowledgeable reader can recognize the reference and avoid being distracted.

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

8. Speaking

 Similar rules have been presented for speaking, the Gricean Maxims: http://en.wikipedia.org/wiki/Gricean_maxim

 9. Email etiquette

Use the same consideration for the reader when writing email. 

First of all, be aware that email you send will stick around forever in some computer files, can be forwarded to anyone on the Internet, intentionally or by accident, and then be read by people that are not sympathetic to you or your ideas.

 Avoid using the option of attaching prior correspondence to your email. If some prior message is relavent to your message, take the trouble to paraphrase the earlier correspondence.  When, say, suggesting a meeting in July, write something as `As you mentioned in your message of 16 April 2006, meeting dates in August will be awkward because people will be on vacation". Such a paraphrase is less of a burden on the reader than having to go through a string of attached messages that are often not visible on the screen

10. Done

Say when you are done. No more scrolling is required.

Dack to the Spring 2008 Schedule, or to the cs73N [Description]. If you want to go back to the 2001/2002 class notes, click .