Style guide
Gareth Rees, April 1996.
-
Present coherent articles as a whole
-
Make sure deep structure is accessible
-
Give an impression of the size of your database
-
Distinguish internal and external links
-
Never use your home page as the startup page for your
browser
-
Don't use links as footnotes
-
Annotate your references
-
Don't discuss your own pages
-
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.
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.
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
toplevel 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:
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:
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:
The startup page for a browser is a place where you put all
the links you use regularly, especially including the major libraries and
metaindexes 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?
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.
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 webcrawling 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.
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.
Mostly from
Jutta Degener.
- Keep to the subject (don't fall into the `provider' role).
- Be specific in anchor texts (don't use `next', `prev', `back', `here').
- Links stress the phrases they are anchored to (so watch out for
consequent clunkiness).
- Plan for search engines (use robots.txt).
- Choose durable filenames.
- Never say `click' or assume your readers have a particular browser.
- Make the document readable if taken out of context (e.g., by printing
it).
- Choose as shallow a structure as possible.
- Present information in several ways if appropriate (you can have a home
page, a table of contents, a graphical overview
and an index).
- Provide a title page for multipart documents.
Email:
Gareth.Rees at cl.cam.ac.uk
Up:
Home
Previous:
Short essays on science fiction and
other books
Next:
Tree fiction on the World Wide
Web