Style guide

Gareth Rees, April 1996.
  1. Present coherent articles as a whole
  2. Make sure deep structure is accessible
  3. Give an impression of the size of your database
  4. Distinguish internal and external links
  5. Never use your home page as the startup page for your browser
  6. Don't use links as footnotes
  7. Annotate your references
  8. Don't discuss your own pages
  9. Other style principles
This material is intended to supplement the CERN Style Guide, not to replace it. Some of it is appropriate to people with big databases of material to organise, other bits are directed at people with lame personal home pages.

Present coherent articles as a whole

Readers understand coherent articles - they see them all the time in magazines, newspapers, journals, conference proceedings and so on. They don't have much experience of reading articles that have been chopped into pieces - and just as importantly, neither do you. If you choose to present your information in a form close to existing forms, then you know what is successful in that form and what isn't. If you choose to adopt a new form, then you had better think very carefully about exactly how to structure your text for best effect. Read the literature on hypertext for discussion of how to structure documents for readability; test your documents on readers as though they were computer programs with strange new user interfaces (which, in a sense, they are).

In most browsers, it's easier to navigate within a page than between pages. Dividing a single text into a number of pages means your readers will have to issue a lot of navigational commands to read it.

At the current state of the Internet, connecting to a site that's distant from you tends to be slow. If you chop your material into small pages, then readers are prevented from following the thread of your argument because of the long wait for each paragraph to download. If your material is presented in one article, then the initial wait is longer, but once the article has been downloaded the reader can give it their full attention.

If you have space, the best solution may be to take advantage of the medium of hypertext and present your article in both ways (as a single complete article, and as a multiplicity of paragraphs), and let the reader choose, depending on their preference.

Make sure deep structure is accessible

In a deep hypertext structure, with indexes at several levels, it is possible for information to be `lost' in the sense that a reader reading the top­level index will be unaware of the existence of that information.

This is most likely to happen if different levels of index organise their information according to different criteria. For example, suppose that a hypothetical university information server has a home page which indexes the home pages of the departments in that university, but doesn't say what information those departments provide. In such a case, you have to guess which department has the information you need before you can find it.

It is therefore important to provide clues at each level indicating what is to be found on each of the branches. Hierarchical subject trees are examples where this works, because the choices at each level provide access to subsets of the subjects named at the level above.

A real example, just in case you think I'm making this all up: try to find the information about free Esperanto lessons starting at the Cambridge University Computing Service.

Having a clear index structure helps you to:

Give an impression of the size of your database

A good way to prevent your readers getting `lost in hyperspace' (a common feeling when browsing a complex structure) is to give them plenty of clues as to how big your database is.

The best clue you can provide is a complete listing of entries (even if such a list isn't appropriate on the home page, it can be provided separately). A top-level index of categories should annotate each entry with the number of documents to be found by following that entry. If you can find an appropriate visual organising principle, then a graphical overview might help those of your readers with fast connections, graphical browsers and colour monitors.

In order to give a correct impression of the size of your database, you need to:

Distinguish internal and external links

Some `home pages' freely mix links pointing to documents in the database at that site with documents stored elsewhere, as though the Web were a single amorphous information resource. But amorphous doesn't necessarily imply useful.

If you maintain a personal home page, then to accomplish this, you should:

Never use your home page as the startup page for your browser

The startup page for a browser is a place where you put all the links you use regularly, especially including the major libraries and meta­indexes on the Web. On the other hand, your home page is a document that describes you to the rest of the world, and lists the resources that can be found in your database. So why confuse the two?

Don't use links as footnotes

Footnotes distract from a line of argument; if the material in a footnote can't be integrated into the body of the text, then it probably doesn't belong in a footnote, either. Just because you can include jottings, notes, side issues and other material in a hypertext document, doesn't mean you have to.

Annotate your references

Please, annotate your lists! Try to provide a short description of the contents of the destination of the link (but use your discretion; some titles are self explanatory and won't need annotating, and an annotation that says nothing useful is as bad as no annotation at all). Think of it as your way of adding value to the list: anyone can compile a list of links (the web­crawling robots have databases with hundreds of thousands of URLs) but you have to read and understand the documents in order to write useful descriptions, and thus make your list a valuable resource.

Don't discuss your own pages

The mere lack of anything to say doesn't stop some people; instead of writing about the world `out there', they discuss their own Web pages - how they were written, when they were written, what's new about them, what their friends had to say about them, what the usage statistics are, who's read them, and so on.

Other style principles

Mostly from Jutta Degener.
E­mail: Gareth.Rees at
Up: Home
Previous: Short essays on science fiction and other books