SLAC CPE Software Engineering Group
There should be a short, one or two sentence abstract at the top of the page which describes the contents of this page. For instance, "This page is the HTML template for CPE Software web pages."
Elements of the page, Style
See also: reference1, reference2 ...
This section describes the TOPIC and TITLE parts of the page.
Beginning at the top of the page, the "TOPIC" should be a one or two word proper noun which identifies the software project, or subsystem. For instance just AIDA or EPICS or CVS. The home page of that topic should be listed at the bottom of the column of references on the RHS of the banner, and in the list of references at the bottom of the page. For large projects, like EPICS, it makes sense to put two links at the bottom of the list under "Software Detailed", for instance both EPICS and then a sub-topic, like IOC.
The TITLE of the page should appear in 2 places. The first is at the top of the page, under the TOPIC. In this example page, it is literally "TITLE, e.g. WWW Page Template". The second is the HTML <title> property of the page - which is the text printed in the top of the browser window, and is used by search engines to identify what your page is about. This page's <title> is "SLAC CPE Software WWW Page Template". To change the <title> HTML tag in FrontPage, pull-down the File menu and select "Properties.." and change the Title entry. In Netscape Composer you set the page title in the Publish process, so if you use Composer to edit HTML but not to publish it, you will have to change the <title> HTML tag by hand in the html source. Look for it in the <head> block at the top of the source. Macromedia Contribute will change the HTML title tag for you when you create the page.
The Contents list above, is a list of HTML targets within this page. In Frontpage these are called "bookmarks": to create them first copy & paste the subheading text into Contents section, then create the bookmark (select the text that will be the target, in this case the heading, pull down the Insert menu, and select "Bookmark". Click OK in the Bookmark dialog to create the bookmark), then link the text in the contents section to the subheading (pull down Insert menu, select Hyperlink, and use the "Bookmark" pick-list in the Hyperlink dialog.
Netscape's Composer HTML editor calls bookmarks by their proper HTML name, which is "Target". In Composer the procedure is similar to Frontpage, use the Insert menu and select Target. The See Also section is a list of useful references to other documents.
This section describes the textual style that should be used for different kinds of text in our documentation.
Use the "formatted" html tag in bold for source code or terminal i/o. Also, if it's input you give at aprompt, preface what is typed in with a prompt sign >. E.g.
> cvs co package/aida
TOPIC is in Normal, Variable Width, 13pt. TITLE is in H1. Subheadings, such as Style and Elements of the Page above, proceed from H2 onwards.
The tables used to space items under heading on index pages are regular html tables, with 2 columns, whose width has been set to 100%, and whose cell border has been set to 0 pixels. The effect of these together is to space two columns of text. Here is an example:
|Left hand column first entry||Right Hand column first entry|
|Left hand column second entry|
[SLAC CPE Software Engineering Group][ SLAC Home Page]
Author: your name, dd-Mmm-year
Modified by: dd-Mmm-yy, user name, short comment. dd-Mmm-yy, username, short comment. Note, all modifications are listed on same line!