head 1.1; access; symbols; locks; strict; comment @# @; 1.1 date 98.09.05.10.51.23; author alexis; state Exp; branches; next ; desc @renamed document conventions to document design and added proper document contentions @ 1.1 log @Initial revision @ text @

Alexis's Helpme Pages: Meta Information: Page Design Reference

Introduction / Philosophy

Okay, call me a fascist, but you're gonna do it like this! If you don't then you're using your fingers too much and your making your documents slower to read and harder to scan.

This document attempts to be only hierachically linked; there is just one reason for this and that is that peer-to-peer and other "horizontal" linking just creates extra stuff to maintain! Documents are linked vertically - always with one parent and any children, but additonally, like Yahoo, linking grandchildren to allow the user to move down the tree faster.

There are only three different templates in use here. They are:

Node: these contain links to the index.html files at the next level down and also links to the very same things that those index.html files link to
Last Node: these contain links to non-index.html files in the same directory, which contain *no* further links
Leaf: contains information! Links are allowed, but only to URLs totally outside this structured document

There should be no need for any other document style!

Don't indent things unnecessarily; it makes it harder to scan.

Don't deviate from the established style; because again, insconsistency slows people down.

No rules lines, non-standard fonts etc; the simpler the better! The aim of this document is to make quickly written, easily read, easily maintained documents. And what *you* might think is a good idea isn't if you're the only one doing it!

Don't specify the email address of a maintainer - that just creates more stuff to be maintained, and the same information will be available under the RCS directories (read on for more information on RCS).

Don't bother putting "last modified" information in. Again the information is available elsewhere and it's just "one more thing to maintain".

There are no icons, backgrounds, etc.

Don't use blank lines, use paragraphs! This means when you move your cursor down a page, you should not be able to put it on the blank bits between paragraphs. It should just move from one to the next. Additionally your cursor should not "get stuck" on a line when moving down. Seem pedantic? Sooner or later you're going to copy a previous document and then everything just starts spiralling out of control. Get it right from the beginning. Call me a fascist if you like.

Unix supports long filenames so why bother making up abbreviations that sooner or later are going to cause confusion or get duplicated? Use file names that match the title! But if you change the title then don't be a lazy sod; change the filename too, Sheesh! it's not much work!

Note that there are no "previous", "next", "up", "down" or "home" links on any pages. There is no need for these; all browsers have sufficient navigation controls themselves.

The pages are stored under RCS in a hierachical arrangement that exacly mirrors the documents' link structure. RCS is beautifully simple; you can consult the man page rcsintro(5) for more info, but basically there are only four things you need to know:

There must be an 'RCS' sub-directory in each directory containing pages; so if you create a new sub-index then you're going to have to create a directory to house the stuff it refers to
To "check out" a document in order to gain exclusive write access to it use the command

$ co -l filename.html

To "check in" a document, for the first time or on a later occassion use the command

$ ci -u filename.html

The text "Header" surrounded by dollar signs (not reproduced here for semi-obvious reasons) is substituted at check-in-time for a string of version information; this is included at the bottom of each page by convention. (under newer versions of RCS this is replaced by "Id" surrounded by dollar signs). Look at the bottom of the page for how this gets expanded!

Note how the prompts in the commands above showed you that these commands were not run as root and were not run on a specific command. Note that the entered text was in bold, whereas what was outputted wasn't. Try to use intuitive prompts like this.

Various fonts have been used, but the templates explain these in greater detail. To determine convention for infrequently used structures such as tables it is best to just look at one!

$Header: /diska/home/alexis/dev/helpme/doc/meta/RCS/document-conventions.html,v 1.5 1998/09/05 08:42:20 alexis Exp $ @