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.

Navigation

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:

Dictionary or Glossary. Here each page (or anchor) is related to a term or keyword and that all the terms are generally 'at the same level'. It's also worth having a 'top page' with a listing of all the terms with links. A user can then jump up and down (in hyperspace!) without getting lost.
Hierarchical Book. Here the structure is Chapter/section/subsection... (We don't recommend going much lower than this). In this case there should be a table of contents, and a mini-table for each i chapter. Each page should have a heading giving the infostructure name and the chapter/section. Whether you put 'Next' and 'Previous' links on each page is up to you.

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:

links within your own hypertree. This is fine - but make sure that you use relative, not absolute, addresses as this makes it much easier to relocate the material.
links to stable, widely used, URLs. If you are going to link to PDB at Brookhaven, it's a good idea to put the absolute URL in your document. Even were the URL to change (and this happens, infrequently but significantly, with major sites) they will always leave a forwarding address.
Links to a flexible, but well-maintained, PPS resource. We are hoping to develop a central Glossary and are delighted that Lesley West, who is an experienced information scientist, has offered to curate it. This has the great advantage that it will be under constant observation, so that terms will be added regularly and any errors will be eliminated rapidly. Also, it is an excellent 'clearing house' for connecting to other resources in the course. Thus, rather than try to point directly to, say, 'How to write RasMol scripts', it will be much more robust to point to 'RasMol' in the glossary and have that entry point to the latest RasMol info.
Links to other authors in the course. If these authors already have stable URLs which existed before the course, like PDB, CCB, RasMol, BBK, etc. that shouldn't be a problem. But it's likely to cause a lot of problems if you link directly to material they are just producing, since it's quite possible it will move in the future. We shall try, during the course, to address this but don't be too ambitious at present.

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:

I have control. I can move material around easily, and alter configuration files.
I have to make sure the server is running, even when I am away on holiday.
Some of the learning curve is quite steep (e.g. clickable maps).
I have to make a case for my own resources. But I may also have more than I get at BBK.
I may have to maintain a lot of software and info. Do I want to do this after the course has finished?

The line may be slow and response poor - it may even be down.
It will take a little time to find my way around.
I don't have to worry about maintaining the server.
There are lots of people to help.

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:

MSDOS/Windows. The filenames on this are case-insensitive and have a maximum of 8 characters per directory, 64 in total. Therefore make sure that the segmentsn of your URL pathnames are unique in the first 8 chars whatever case.
PC Mosaic. This does not display several small gifs on a line properly - they are vertical rather than horizontal. Non-existent URLs crash my version, so please be careful.
GIFs. We welcome beautiful GIFs of proteins and realise that these may be large, but are worth waiting for. However, please remember that some people have very slow lines (2400) and that a GIF can take minutes to download. Please try to keep non-essential GIFs small. This is possible if you use small pictures with a small number of colours and not too much detail. (For example, don't have a home page with an inline photo of the people in your group - add a link to it with a message like:
<a href="ourgroup.gif">Picture of our group (76K)</a>. Avoid texturing (marble, fabric, reflections) on GIFs unles there is a scientific point.
It may be useful to have mini-gifs which show what the large picture will look like:
<a href=big_insulin.gif><img src=mini_insulin.gif> Insulin (67K)</a>
Forms. We are committed to using forms and all students will have to find some access to a browser that supports them. There are definitely glitches with some browsers. At present:
- Some browsers struggle if there are a lot of entry boxes on a page, so try to be careful how many you use.
- Some (certainly SG) have very small textarea boxes. This is not really an authoring problem, but some people might think it was the author's fault. Obviously you should set the textarea box large if you are expecting a lot of text.

Client-side (Forms and Imagemaps)

A number of things require client-siide management, and this causes the following problems for authors:

The html pages have to be kept in synchronisation with the CGI pages. This may mean that when you alter the html page containing a form you have to simultaneously alter the CGI script. Obviously it's easy to make errors here. I don't yet think there is a generic approach to this.
The author has to have access to certain client-side configuration files. For FORMS she has to be able to access the scripts in the cgi-bin (or equivalent) directory, and probably has to have an account. For imagemaps the imagemap.conf file has to be edited for each new clickable map, which clearly requires coordination.

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>

Hardcopy

I get asked "can we download the course so we can view it at home?". At present we should think about:

Some people have very slow lines so this would be very useful.
Much of the course material is on remote machines and is either difficult to download, or we are not allowed to do so.
There would be a tendency for some students not to interact with the course.
It's a lot of work, since we have to do this regularly to keep up to date.
Unless you have a CGI server running at home , things like clickable maps and forms won't work. Porting the server-side stuff is also non-trivial.

I think we should keep this as an important issue and discuus it openly to see what seems possible and desirable.

Latex2Html

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.

Copyright

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