![[ example of login screen ]](guidelines/guidelines_login.png)
guidelines_login.png
2. General remarks
2.1 Audience
2.2 Markup the markup language
3. The headers
3.1 The chapter title
3.2 The section titles
3.3 Sub-sections
3.4 Example of code of headers
4. Images in the text
4.1 Embedding a image
4.2 Explaining the image
4.3 Guidelines for images and explanations
4.4 Example of code of image
8. The use of entity names in HTML-tags
8.1 Showing the special characters
8.2 Bold text
8.3 Italics
10. On Emphasis in the Texts YOU PRODUCE
11. Other chapters and revision date
A notice about 'NOTICE:'. When you find a 'NOTICE' in the text, it
contains information that requires special attention. The notice
should always start on a new line. The easiest way to achieve this is
to insert a P-tag before the notice. After the
notice, the regular text continues. This regular text should be
separated from the notice, e.g. by inserting another
P-tag. Of course this is not necessary if the notice is
at the end of a section.
NOTICE: this paragraph is delimited from the previous one with the
P-tag <p>. For easier readability we
never use the closing P-tag </p>. In
order to improve readability of the source code you should always use
lower case in HTML-tags.
These audiences have varying levels of expertise. The local systems administrator knows a bit about Linux and has a fair amount of Windows knowledge, the ICT coordinator knows about education and has a bit above-average Windows experience and teachers and pupils have little or no experience working in a network environment. Therefore each audience needs step-by-step guides, tailored to their level of knowledge.
A fine example of a step-by-step guide is the GPS guiding system in your
car. You have to drive the car, observe the other traffic and listen to the
friendly woman's voice saying: "Turn left in 30 meters".
Your attention is divided. When the system misses one side street, you are
completely lost. When you oversee a small street, you are lost, too.
The same happens in a manual. The one who uses it, is reading about, and working with an application.
Here are my rules of thumb when writing a manual:
NOTICE: At the end of each section you must be able to return to the top of the chapter (the table of contents of the chapter). Since we are now at the end of this section there is an example on the next line...
...right here: (top)
H1-tag per
chapter. This is the chapter title. This title is located almost at
the top of the document, right after the standard Page Navigation
Header. The text between the H1-tags is also part of the
text in the TITLE-tag in the HEAD-section of
the HTML document.
NOTICE: The number of the chapter is also included in the title.
The name of the book of which this chapter is a part
is shown in the first row of the standard Page Navigation Header. An
abbreviated title of the book can be added to the
title-tag in the page header, e.g. 'Guidelines -
II. Guidelines by example'.
H2-tag. You can use as many
sections as necessary to say what you have to say. Note however, that
when you have many, many, many sections, you probably need to split
your document into different chapters anyway.
Section titles all have a name. This name is used to link to the section from the table of contents at the top of the chapter. Every section ends with a clickable link to the top of the document.
H3-tag. They do not necessarily have
a name, though it is not verboten. The HTML markup language
defines a total of seven levels (from <h1> to
<h7>). Please try to use no more than three
levels in your document. In the end sub-sub-sections make your text
more difficult to read rather than easier.
NOTICE: Chapter titles and (sub-)section titles do not end with a period. A capital is only used at the beginning of the line.
|
Note that the links to the sub-sections are indented using the old-fashioned way of adding two non-breakable spaces. This yields good results, even with text-mode browsers like Lynx.
NOTICE:
In order to avoid name clashes with references to subsections, you should
use a dot to separate the section number from the subsection number in
the name and href attributes. If you have
two subsections, say 1.23 and 12.3, the sections should have names
like <a name="h1.23">...</a> and
<a name="h12.3">...</a> If you do
not use a dot, both names would look like <a
name="h123">...</a> which would be very
confusing for web browsers.
WIDTH- and a
HEIGHT-attribute with the correct dimensions of the
image;
ALT-attribute which describes the image
in plain text;
SMALL-tag) and at the same time emphasized (using the
STRONG-tag);
BR-tag;
P-tag;
Explanation:
P-tag.
guidelines.html, this would yield
guidelines.
login.png rather than a systematic name such
as image00001.png.
_'.
guidelines_login.png) is
stored in a subdirectory which is also named after the file
from which the image is referenced (here:
guidelines.html) but once again without the
extension. Therefore the image is referred to with
guidelines/guidelines_login.png.
BR-tag.
STRONG-tag for the items. Make sure the name of
the item is exactly the same as in the image, if applicable.
P-tag after the list.
When an in-line image is required in the text, e.g. a small
icon image, a title under the image and a border around it would
disturb the layout. In this case, use the title attribute
for the name of the image. A border is not necessary so set the
border to 0 (zero).
NOTICE: if the image is not followed by an explanation (and
hence not the word 'Explanation:'), a P-tag should be
used to separate the image from the subsequent running text.
NOTICE: In an ideal situation the names of the chapter file (here:
guidelines.html) is as short as possible, preferably
fitting in the legacy 8.3 filename format. This implies
an extension of .htm rather than .html.
However, there is no real reason to stick to this old-fashioned and
inflexible file naming convention. You can already see this in the
names of the image files: following our own convention of using the
name of the HTML-file followed by an underscore, followed by the rest
of the name followed by the extension, makes it hard to keep the
filename in the aforementioned 8.3 format. However, we
do want you to stay away from spaces in filenames (use
underscores instead). Furthermore, please use all lowercase letters
for filenames.
|
An in-line image does not have a border nor a title under the
image. Instead the name of the file is shown in the title
attribute. This is shown in the code snippet below.
|
NOTICE:
In the larger images (centered, with border), the title
attribute is optional because the name of the file is already displayed under
the image. For in-line images such as icons, the
title attribute is mandatory.
OL-tags) or unordered
(UL-tags)lists. Since the closing tag
(</li>) is optional according to the HTML 4
specification, there is no need to add these. However, you can add
those closing tags if you prefer.
| length | explanation |
|---|---|
| 0 | When you put in a 0 (zero), no input field will be made. This is a useful feature to put extra information in the form that needs no responding to. |
| 1 | you will get a checkbox with yes and no. |
| <= 80 | a normal input field |
| > 80 | if more than 80 characters a textarea will be displayed |
The table is separated from the running text with a
P-tag. A table is supposed to have at least the following
attributes:
After opening the table you should add a table caption in the special
CAPTION-tag (here: "The length in characters of
the input field for the expected response
text"). Immediately after this table caption the table
itself begins. It can start with a table row (<TR>)
and the special header data (<TH>), or you can
begin directly with a regular table cell (<TD>),
depending on whether you do or don't want to have column headers that
are rendered differently from the rest of the table. In the example
above the special headers (<TH>) were used.
Note that you can use attributes like VALIGN and
ALIGN in table data elements where you see fit.
After the table is closed, you should add a P-tag to
separate the table from the subsequent running text.
[access log site@school] [127.0.0.1 on 26-2-2004 at 14:48 userid:admin]
Use the PRE-tags to create preformatted text, e.g. to
show command line output.
If you want to show a piece of code, e.g. an HTML-tag, use the
CODE-tags. (We use them all the time to show HTML-tags in
this very text.)
<, > and &
directly in the HTML-text but use >,
< and & instead. You need
this when you want to write something like this:
Start > Settings > Control panel > Documents & Files
Also, use " rather than a bare
" because it might confuse some browsers.
B-tag to show text with the bold
attribute but use STRONG instead.
I-tag to show text in italics;
use EM instead.
If it is at all possible, try limit the line length to less than 80 characters. This makes the HTML code readable, even on a text-only terminal.
EM-tag instead. Do not use all upper case words in texts
to emphasise. Use the STRONG-tag instead.
Use the single quote to emphasise something special. For example:
The use of 'Janitor' is not so difficult.Use double quotation marks to quote. Example:
As stated earlier, "never use passwords like 'test' or 'admin'".Also, remember to use
" rather than a bare
" because otherwise some browsers might get
confused.
NOTICE: The text must have a revision date and it must be at the end.
This is also part of the standard template. See the last line of the
footer below (just underneath the line identifying the author). Note
that it is perfectly acceptable to use a CVS-tag such as
$Id$ or
$Date$ for this purpose.
syntax errors. A particular handy tool is a Perl-script
called weblint. This fast script reads your HTML-file and
reports a lot of common mistakes, e.g. missing closing tags,
overlapping tags, etc. etc.
And of course there is always the W3C Validator, located at http://validator.w3c.org.
Good luck with writing and watch out for that (writer's) block!
Author: Peter Fokker <peter (at) berestijn.nl> $Id: guidelines.html,v 1.9 2006/04/05 14:36:15 peter Exp $