|
|
HTML Documentation GuideDOC-STY-3$Revision: 1.4 $ |
This document is a set of advisory criteria to be used when writing documentation for Web publishing at ING.
It is not intended to restrict in any way the layout or content of the web-page. The intention of this document is to enforce a minimum standard of information in the web-page document so that automatic mechanisms may be employed for cataloging the many web pages which are available on the ING site.
The document assumes that you are familiar with HTML tags, If you are not then the use of a HTML editor with a graphical user interface (GUI) is required.
ING Web documentation is to be written to the XHTML Version 1.0 Standard. This requires the first line of the html source file to contain the following definition:-
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "DTD/xhtml1-transitional.dtd">
Authors may check that the document conforms to this standard with the URL:- W3C HTML Validation Service
It is advised to use style sheets (CSS) when writing online documentation as this will give a standard look and feel to ING documentation.
This is the information required between the <head> and </head> HTML definitions.
An example of the text between the head definitions are:-
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="GENERATOR" content="Mozilla/4.04 [en] (X11; I; SunOS 5.6 sun4u) [Netscape]">
<meta name="Author" content="Dennis Armstrong">
<meta name="Keywords" content="Isaac Newton Group, documentation">
<meta name="Description" content="HTML Documentation Guide">
<meta name="Classification" content="PRIVATE">
<meta name="Issue" content="0.1 1999-07-04">
<title>HTML Documentation Guide</title>
<link rel="stylesheet" type="text/css" href="../../../ing_csg_standard.css" title="Standard Document Stylesheet"></link>
The META information which is important to ING and is required are:-
Put your name in the content="A. N. Author" place.
Add keywords which will assist in finding the document. Separate them with the use of a comma.
Describe the documents function ie user guide to xxx
Three classifications are defined. Use either PRIVATE for ING usage only or PUBLIC for external web accessed pages. For personal web-pages use the PERSONAL meta name. The default Classification is PRIVATE ie internal ING.
The issue number in the form Major.Minor and optionally the date in iso8601 format. ie yyyy-mm-dd
The information may be added with use of a simple editor, vi, nedit, emacs etc or with one of the web publishing packages available.
Several HTML editors have the ability to include this information as part of the editing process.
If Netscape Composer is used for the web-page composition then it is very easy to add this information. From the Format menu select the "Page colors and Properties" option. The pop-up window has 3 tabs.
Most of the information can be entered in the general window:-
The Advanced tab is required to add the meta name="Issue" information.
If Star Office Version 5.1 is used then this information may also be added. From the File menu select the "Properties" option. The pop-up window has 5 tabs
Most of the information can be entered from the Description tab :-
The Title window is for the <title> META tag.
The Subject window is the <meta name="Classification" > META tag with a default content="PRIVATE".
The Keywords window is of course for the <meta name="KEYWORDS" > META tag.
The Comment window is for the <meta name="DESCRIPTION" > META tag.
For the META TAG <meta name="Issue" > the User Defined tab is used, which will pop up the following window:-
To edit the user definitions click on the "Info fields.." button to obtain the Edit Labels window. This will produce a window in which the "Info 0" label can be edited. Change the "Info 0" text to "Issue".
Click on OK in the Edit Labels Box to pop down the Edit Labels window:-
The User Defined window now has a label "Issue". Edit the Issue field and click the OK button on the Properties box to save the information for this document.
The META tag <meta name="Author" > should have already been setup during the installation of Star Office. It can be changed from the Tools->Options->General->User Data information box. It is the First/Last name part of the form.
This is the only part of the html document that the viewer will see that is specified in this document. The copyright information and Last modified date are required with a link to the webmaster@ing.iac.es mail address. This requirement is for the reporting of errors in the HTML document.