Style Guide for Contributors

This course will have contributors from many different labs and so there will be a variety of styles in the hyper-resources that we have in the course. It's quite an effort to write really good hypermaterial - I know! - so here are some guidelines that I hope you will find useful.


Even though you may think your hypertree is easy to understand, it's likely that people will get lost in it, unless you give them clear signs as to where they are and where they might go. (Unless, like Alice and the Cheshire Cat, you don't really mind where you go.)

A typical problem is that you read through a series of pages and then decide that you want to 'jump out' of this area. Unless you have a good 'Window History' manager, you have to keep hitting 'Back' - maybe reloading pages every time - until you come to where you 'came in'.

Another problem is that people may put links into the middle of your material. It's important that the voyager knows that they have 'jumped' into another document, because unless they follow the URL addresses there is no visual clue. (Not all browsers have these addresses anyway).

So a general recommendation is that every page should have a brief identifier for the infostructure it belongs to; and that it should have navigation butons that allow the user to go to its root. This could be a table of contents or other page.

After a lot of experiment I suggest that - for now - you try to stick to one of two classic structures:

The clickable map is an excellent way of navigating certain types of info, but see below...

Validity and Ownership

I find it extremely useful if I can see when a page was written and updated and who the author is. It's very difficult when you think that a page is no longer maintained, but don't know who to ask.

Cross-referencing and the Glossary

It is extremely valuable for us to put crosslinks into our material, but this is going to take a lot of organisation. I can see the following approaches:

Remote Links and Local information

If you are just starting with producing HTML documents, you may be wondering whether to set up your own server, or to get an account with Birkbeck and mount the documents there. Think about the following:

Some of you will already have material that existed before the course. This isn't the course's property (!) and remember that there may be users from other disciplines or not on this course. The course organisers have no rights to do anything other than point to these resources, although the authors may grant additional ones. (For example, you may be allowed to read the material, but not to download it for any other purpose.) The course is, of course, extremely grateful to those who are cooperating with us.

Technical Problems - DOS, Gifs, Forms and Imagemaps

There are a number of technical problems which you should bear in mind when creating documents. HTML was conceived and developed in a UNIX environment, and some things don't (yet) port automatically to otehr platforms. Here are a few things to think about:

Client-side (Forms and Imagemaps)

A number of things require client-siide management, and this causes the following problems for authors: I am sure we shall work out a harmonious way of doing this.

MIME types

Clever use of MIME types allows the server to send very powerful scripts to the client which can exceute them, but this can be a security hole. However we anticipate having certain MIME types for the course which will allow safe use of sophisticated clients (RasMol, Mage, WPDB, etc). Until we get soem idea of what members can do what andi define a convention, it's probaly unwise to assume that the client has a specialised viewer. You might write something like:
<a href = insulin.pdb>View Insulin with RasMol</a>
<a href = insulin.gif>View Insulin as a GIF</a>


I get asked "can we download the course so we can view it at home?". At present we should think about: I think we should keep this as an important issue and discuus it openly to see what seems possible and desirable.


I have been very impressed with this software (Nikos Drakos, Leeds) for maintaining a complex hyperresource. If you know LaTeX, and have a medium-sized infostructure it's well worth looking at. It manages image conversions, cross-references, LaTeX macros, and many other things very nicely. If you want to prepare a printable version of your hypertree, I'd definitely recommend it.

We may start using it for bits of our material.


I have written about this already, but please remember that material which is not yours is probably copyright unless it specifically says otherwise. This applies to journal articles, diagrams and text in books and magazines, and almost everything on the Web. (For example this document is copyright automatically - I don't have to add the Copyright symbol).

up to index
pmr for pps
Dec 4 1994