Notes on User-Level Documentation

S. Digel, 21 June 2005

There's real progress to report.  I am not sure how much of this has been discussed in meetings over the last couple of weeks or circulated via e-mail.  What I've written below may not be more than half baked.

Chuck has prepared an HTML template for the user-level documentation of the science tools.  With Matt's help, Chuck's Web-accessible development area for the documentation is also online.  (With a SLAC account, you should be able to open and edit files in this area - see below.  This means that you can also overwrite files, so be careful.  The system is smart enough to recognize if someone has a file open at the same time that you do, or if it has been saved by someone else while you are editing it.)

Placeholders for the documentation are online here.  In particular, see the generic example for the tags that are available and the Dream Weaver Template (which FrontPage also opens). 

Note that this documentation development area is not directly connected to the User Workbook.  Chuck will be the gatekeeper for moving documentation into the workbook. 

To be done:

• Establish the Platonic ideal of a reference page and of an analysis thread (aka tutorial).  So far glbary and pulsePhase are the most developed examples of reference guides, and the Likelihood and gtpsearch tutorial are the most developed examples of analysis threads.
• I think that for all of the tools in the documentation area for which at least some user-level documentation was available (e.g., as a couple of paragraphs in the Doxygen documentation), Chuck has made an HTML marked up version with the tags that we'll be using.  Of course, this should be understood to be just a starting point for the Subject Matter Experts to take off from.  So it is time to start writing.
• Also regarding threads, ultimately the idea will be to have them not overlap, especially in terms of common steps, like data selection.  And we'll need to establish a naming convention for folders containing threads.
• For the User Workbook, we'll have to sort out how to arrange the different levels of the Science Tools toolbars for the reference guides and for the analysis threads.  The GSSC may want to do its own thing for the presentation and distribution of the user-level documentation.
• We will have to figure out a common way to document the sources available to gtorbsim, although of course this documentation may ultimately exist elsewhere in the User Workbook.  We've got a start on this in Jim's Doxygen documentation of observationSim sources and in the science tools area of Confluence.

The HTML markup that we are using may ultimately prove to be a stop gap for something more general (like DocBook), which can be used to generate HTML and as well as formatted documents (like books with tables of contents, indexes, etc.).  My impression is that Chuck thinks that a conversion would not be hard, and would not be a burden on the Subject Matter Experts, or at least not much of one. 

Excerpt from a note from Matt on accessing the documentation files for editing:

> Hi Chuck,
>
> I've set up a "workspace" for you and your documentation
> collaborators. Technically, it is called a "WebDAV site", but
> Windows users will call it a "Network Place". Linux people have full
> access too, but they tend to be an independent bunch with their own
> opinions and ways of doing things so they will probably want to
> access the site in whatever ways they know or want.
>
> To access it from Windows, add a Network Place (Start > My Network
> Places > Add a network place). The "Internet or network address" is
> http://glast-ground.slac.stanford.edu/documentation. You use your
> Windows username and password. Currently the Windows group (which we
> control) named "Glast Web Authors" has full control of this site,
> and current members are you, Richard and me. Tell me who you want to
> have access to it and I'll add them to the group. Then they can do
> whatever they want (create/delete/move/rename/drag-and-drop folders
> and files, etc.).
>
> To access it from Linux, there are tons of "WebDAV clients". You
> will probably just have to mention "WebDAV" to your Linux
> collaborators and the address
> (http://glast-ground.slac.stanford.edu/documentation) and they will
> know what to do.