Minutes February 12, 2002
Attendance: Joanne Bogart, Heather Kelly, Bob Schaefer, Alex Schlessinger, Mark Strickman, Karl Young
Code Documentation Recommendations
We should require a doc directory in each package - if this is not already
explicitly stated it should be.
TkrRecon Code Documentation Review
The review will take place on Wednesday Feb. 27th at 8:30 AM via VRVS.
Joanne kindly volunteered to take minutes during the session. We hope the
session will go something like this:
Brief introduction to TkrRecon
Review Doxygen output
Review source and header files
The TkrRecon group can provide a tagged version from which the Doxygen
output will be generated or we will use the HEAD. We do not expect to
review every source and header file in the package. We will focus on those files
that the TKR team has had time to upgrade to conform to the code documentation
rules. If this proves to be too much to view in the time allotted -
we will randomly choose some of the files. The review team will produce a
write-up of resulting recommendations.
Web Recommendations
A draft of the web recommendations is now available. All are
encouraged to take a look and provide suggestions and update the text. We
have a document number for CyberDocs- thanks Richard. We will submit our
document when we have completed the web recommendations section. (Though
we do intend to add more sections concerning tutorials, user guides, etc in the
coming months)
Organization was discussed. Mark specifically mentioned the desire for a site map or indices that would provide users a mechanism to navigate the SAS web. There are many pages that are difficult to locate. The difference between physical and virtual organization was noted. We will be more concerned about the virtual organization, rather than the folder arrangement.
Among the web recommendations is a new one suggesting the use of metadata, specifically setting title, keywords, and a description for each web page. Metadata will aid in setting up search engines for our web. It was suggested that we may want to set a list of standard keywords that would help in searching. Karl offered to contact SCS about setting up a web search engine for the SAS pages.
Karl mentioned that Babar's web recommendations include noting both the creator and maintainer for pages. We do have situations where this may be suitable. We could mention this as an option within the web recommendations - but not mandate it.
Web Review
Karl, Mark, and Heather volunteered to participate in the upcoming web
review. This will be the first such review and will hopefully result in
revised organization and content. Joanne agreed to take a look at the
existing SAS home page and to offer some organizational suggestions.
Web Templates
Joanne had suggested that we should provide examples demonstrating how to
accomplish some of the web recommendations. A new page has been created
providing information about web templates and providing links to download them.
http://www-glast.slac.stanford.edu/software/core/Documentation/templates/default.htm
A template for Apache servers is available. The page includes title, date,
and time stamp. Additionally, Front Page offers a mechanism to share
templates on a web. A new Front Page template has been created called
GLAST_ContentsOnLeft.
Action Items:
Karl will contact SCS concerning setting up a search engine.
Joanne will look at the existing SAS home page and make some recommendations.
Heather will check the code documentation document to be sure we require the existence of the doc directory in packages.