Document #	Date	
	LAT-TD-xxxxx-xx  	February 8, 2002	
	Author(s)	Supersedes	
			
LAT Technical Note			
	System or Sponsoring Office	
	Science Analysis Software	
Document Title	
 SAS Recommendations for Documentation	

CHANGE HISTORY LOG
1.  ABSTRACT
2.  DEFINITIONS
3.  Introduction
4.  WEB ORGANIZATION
4.1 Introduction
4.2 The SAS Software Web
4.2.1 Access to the SAS Software Web
4.3 Web Folders
4.3.1 Naming Folders and Files
4.4 Web Pages
4.4.1 Author, Date, and Time Format
4.4.2 Title, Description, and Keywords
4.4.3 Web Page Templates
4.5 Web Maintainance
4.5.1 Removal of Web Pages
6.  SUMMARY OF RECOMMENDATIONS
7.  REFERENCES

CHANGE HISTORY LOG  
Revision	Effective Date	Description of Changes	

0.5	Mar 11, 2002	HMK:  Created separate web recommendations document.	
0.4	Feb. 8, 2002	HMK and JB:  Insert stronger more clear language in the web section.  Expanded recommendations for web reviews.	
0.3	Jan. 18, 2002	HMK: Separated into 4 documents - one master and 3 subdocuments.  Modified code recomendations:  Inserted example implementation comment block and inserted new section concerning the ChangeLog.	
0.2	Jan. 17, 2002	MSS:  Modified Code Documentation Introduction to include goals of and guidelines for code documentation.	
0.1	Jan. 15, 2002	HMK:  Inserted new section on Requirement and Design Documents.  Converted examples to use JavaDoc style Doxygen comments.	
0.0	Jan. 9, 2002	initial version	

1.  ABSTRACT 

 This note gives recommendations for GLAST SAS documentation, the expected content, the access to documentation and the tools to be used to produce the documentation.

2.  DEFINITIONS

SAS – Science Analysis Software
TBD – To Be Determined

3.  Introduction

4.  WEB ORGANIZATION

4.1 Introduction

It is very useful to build up documentation as work progresses.  The easiest way to make information accessible to others is via the web.  Our web pages will be the first view many will have of the SAS effort.  That being the case, care should be taken to provide easily accessible, informative, and accurate web pages.

4.2 The SAS Software Web

The primary web for the SAS is located at http://www-glast.slac.stanford.edu/software, and will be referred to as the SLAC SAS web in this document.  The SLAC SAS web is on a Windows server.  There is also a unix-based web server at SLAC, which will be primarily used to store machine-generated web pages.

Those web pages that are not stored on the SLAC SAS web, may be located on other GLAST webs maintained at other institutions.  While auxilary web pages may be kept on other webs, the underlying SAS web structure should be maintained on the SLAC SAS web.  Any web pages maintained on other GLAST webs should be properly linked from a page stored on the SLAC SAS web.  To insure web stability, GLAST pages must not be kept within a user's private space.

4.2.1 Access to the SAS Software Web

To create and modify web pages directly on the SLAC SAS web requires a SLAC Windows NT account and access to Microsoft Front Page.  To obtain a SLAC account please see the following web page:
http://www-glast.slac.stanford.edu/software/getting_a_new_slac_account.htm
If you do not have a Windows machine or access to Microsoft Front Page, you can also use Citrix, a product which allows you to log on to a SLAC Windows server  remotely .  For more information concerning Citrix, please see:  http://www2.slac.stanford.edu/comp/winnt/wts/citrix_at_slac.html

4.3 Web Folders

The web folders defined in the SLAC SAS web (http://www-glast.slac.stanford.edu/software) will determine the overall structure of the SAS web.  Each main GLAST SAS subtopic should have its own folder under the SLAC SAS web.  The current set of top-level folders on the SLAC SAS Web is displayed in Figure 1.

Figure 1.  The current set of folders in the SLAC SAS web

It is recommended that each top-level folder contain a subfolder named images to store image files for inclusion on web pages.  If a top-level folder is dedicated to providing information about an external library, such as ROOT, then those pages that are specific to a particular version of that library should be organized beneath a subfolder named according to that version e.g., root-v30006.

When creating web pages on the SLAC SAS web, it will be necessary to determine where to store the files.  There may no folders that are appropriate for storing the new web pages.  Before creating a new folder, do the following:
•	Check to see if there is an existing top-level folder that fits the category.
o	If a top-level folder is found
•	Determine what subfolder suits the category.
•	If no subfolder is found that suits the category, contact the page author of the home page for that category to request that a new subfolder be created.
•	Store the web page(s) in the subfolder.
o	If no top-level folder is found, contact the SAS core software group to request that a new folder be created.
•	Once the folder hierarchy is created, store your web pages in the appropriate folder.

4.3.1 Naming Folders and Files

The naming conventions for web folders and web pages are:
•	Do not use special characters or spaces
•	Avoid upper case letters
•	Use less than 15 characters
It is recommended that the main page for a folder be named "default.htm".  This is the page that will appear automatically when a web browser is pointed to the folder.  Those folders that do not include a default.htm file will have their contents displayed directory style.  See Figure 1:

Figure 1.  View of a folder without a default.htm page.

4.4 Web Pages

While developing web pages, it is important to consider the organization and presentation style used.  Web pages must be accessible on all of our supported systems:  Windows, Linux, and Solaris.  In addition, web pages should be viewable by users of both Netscape (versions > 4.7) and Microsoft Internet Explorer (versions >= 5.0).  Typically this implies that all pages are in HTML or PDF, however, other formats are allowed.

When developing web pages that are stored using a web other than the SLAC SAS web, determine where your web page(s) should be linked into the SLAC SAS web.  Contact the page author of the SLAC SAS web page to request a link be created from the SLAC SAS web page to your web page.

4.4.1 Author, Date, and Time Format

All web pages must have the author, date, and time last modified at the bottom of the page.  If the month is indicated with a number rather than month name, use the ISO Standard 8601.  This means that dates should appear in the form:
yyyy-mm-dd 
where January 2, 2002 would be 2002-01-02
The time uses the 24 hour clock and, with additional (required!) timezone information, would have the form:
hh:mm:ss annnn
for example
16:23:17 -0800
Other formats are permissable as long as they are unambiguous, for example
31-Jan-2002 09:32:22 PST

The setup to display the last modified date and time varies according to the type of web server.  Here are a couple of examples for a unix-based Apache server and Windows:

Last modified: <!--#echo var=”LAST_MODIFIED” -->

Example 1.  Directive for the SLAC unix-based Apache server

Please note that the file containing this directive must have filetype shtml (e.g. must have a name like myFile.shtml) for the directive to be obeyed.

If using Microsoft FrontPage to write a web page to a Windows web server, one adds the date and time by doing the following:

Click on the Insert menu
Choose "Date and Time" 

Here the drop down menus have been used to 
select ISO date and time format with timezone.

Use the drop-down date and time format menus to 
select ISO format with timezone information

Example 2.  Setting up date and time using FrontPage

4.4.2 Title, Description, and Keywords

In the interest of making the SAS web searchable, it is suggested that all web pages contain some metadata.  All pages should be assigned a proper title.  Additionally, one may want to add a description or define keywords that are pertinent to the page content.  

To add a title, description, and a series of keywords directly into the HTML code:
<HTML>
<HEAD>
<TITLE>GLAST Documentation Home Page<</TITLE>
<META NAME="keywords" CONTENT="documentation, web, code, doxygen">
<META NAME="description" CONTENT="documentation guidelines"> 
</HEAD>

To add or modify the title via FrontPage:

Right-click on the page or use File menu, select Page Properties
Edit the Title in the General tab

Example 3. Setting up the title of a web page in FrontPage

To add a description and keywords:

Click the Custom tab
Under User variables click the Add button:

Example 4.  Setting up metadata such as keywords in FrontPage

4.4.3 Web Page Templates

Templates for standard web pages have been created and are available for general use.  Use of templates is not required, but is offered as a means to ease adherence to the web page recommendations.  There are different ways to use the standard SAS web page templates, depending upon how and where you develop web pages.

Developing web pages without Microsoft FrontPage
The templates are available for download from the Documentaion Task Force web site:  http://www-glast.slac.stanford.edu/software/core/Documentation

Using Microsoft FrontPage and connecting directly to the SLAC SAS web
The templates are already available when you go to create a new web page.  The GLAST SAS web templates have been stored directly on the SLAC SAS web.  FrontPage will ask you to choose the format for the new page, included in those options, will be types named "GLAST_*", e.g. GLAST_ContentsOnLeft.  Choose one of these GLAST options, and your new page will take on the format of the template.  Please update the title and author appropriately.

Using Microsoft FrontPage, but not connecting to the SLAC SAS web
The templates are available for download from the Documentaion Task Force web site:
http://www-glast.slac.stanford.edu/software/core/Documentation

4.5 Web Maintainance

Periodically the SAS Software web should be checked for broken links, contradictory pages, and inaccuracies.  It is recommended that such reviews take place every six months.  This task will be shared.  A team of two to three people will be appointed for each web review.  Their task will be to review the content and arrangement of the GLAST SAS web pages.  Page authors will be contacted to fix those pages that are found to be deficient.

Microsoft FrontPage provides tools that generate reports concerning the status of web pages, including the existence of broken links.  To have FrontPage generate a list of broken links do the following:
•	Click on the View menu and choose Reports and then choose Broken Hyperlinks
o	FrontPage will take a few minutes to generate the list for the whole web.
•	The resulting list may look like:

One can then go through each broken hyperlink and attempt to fix them or contact the page author to inform them that there are broken links on their pages.

4.5.1 Removal of Web Pages

In general the removal of web pages is not recommended.  Care must be taken not to delete a piece of GLAST history.  While obsolete information should be removed from public view, and old pages should be stored for posterity.  In all cases, whether updating or removing a web page, broken links must be fixed.

6.  SUMMARY OF RECOMMENDATIONS

Web Organization
•	The SLAC SAS web will be the primary web.  Web pages may be maintained on other GLAST web sites, but must be linked to a page stored in the SLAC SAS web.
•	All web pages should be viewable on all supported systems:  Windows, Linux, and Solaris.  Additionally pages should be accessible using Microsoft Internet Explorer >= 5.0 and Netscape > 4.7.
•	Web pages should have an author, last modified date, and time at the bottom, where the date must be in a form that is not ambiguous.
•	Defining metadata on web pages is encouraged - specifically setting the title, keywords and description items on each page.
•	Before creating a new web top-level folder on the SLAC SAS web, check to see if there is a suitable folder in existance.  If not, contact the core software group to suggest a potential addition.
•	Web reviews will occur on a regular basis (every six months) conducted by a group of 2-3 alternating team members.  The reviews will focus on content and adherence to the web recommendations.

7.  REFERENCES

1.	CERN Web Services, http://webservices.web.cern.ch/WebServices/
2.	BaBar Web Authorship Guidelines, http://www.slac.stanford.edu/BFROOT/www/Computing/WebTeamPages/NewWeb/guidelines.html