I just set up the LCD package at Vanderbilt and Richard asked me to comment on
the documentation from that point of view. Probably much of what one needs to
know is documented somewhere and in some form. The question is whether there is
enough and whether it hangs together well enough to be usable. The answer is
relative to the background of the user. As an experienced SLAC LCD developer it
was adequate for me. However, I was setting up the package at VU because the
documentation proved to be inadequate for the new players at VU.
If we think the system will be installed numerous times in the future then we
need to improve the doc. If we are going to do that it should be done as a
serious integrated project involving a lot more than a few hours of work. I
think three things are needed, a total system description, a set of installation
manuals and a set of user's guides. An extensive description of the E N T I R E
system in one coherent integrated unit is needed. That includes things like
overall philosophy and design. This is where a newbie would go for orientation
when one is confused about the relationship of parts. This is where one would
first go for a glossary of jargon. The detailed installation documents for the
various pieces need to all be written in a unified way. By "unified" I mean
making the same assumptions about the user's knowledge level, using consistent
terminology, and having pointers back to the aforementioned overall system
description. The user's guides would also be consistent with each other and be
integerated with the overall description document.
For products of independent origin, eg, stdHEP, we would point to this
documentation and have additional documentation of our own on its relationship
to LCD.
As a first step here is an outline:
Topics for THE TOTAL SYSTEM OVERVIEW DOCUMENT
egcs
stdHEP
GISMO
ROOT
JAS
generators
LCD detectors
reconstruction
analysis tools
class structures
I/O
platform issues
implementation issues
- directory structure
INSTALLATION MANUALS
pointers to existing manuals for egcs, stdHEP, GISMO, ROOT, JAS, and to
indvidual generators
the generator system
the simulation system
a general installation manual that covers issues about the relation of specific
installations to each other and to the system as a whole (eg, install A before
you install B.)
USER MANUALS
pointers to existing manuals for egcs, stdHEP, GISMO, ROOT, JAS, C++, JAVA, and
to indvidual generators
generating events
simulating events
doing analysis
I/O and class structure issues relevant to the system user.
I imagine we would implement this in web/hypertext by a combination of writing
some new stuff, revising some of the current web stuff and simply pointing to
some of the current material.
This is intended partially to be provocative. What do you think, in general,
about the current documentation? If it needs improvement what do you think of
the general approach presented? Given the specific proposal above what would you
add to the outline? I don't know if or when something further will be done but
while it is fresh in my mind I would like to compile a first draft of the
outline including your input in case we do pursue this at some time in the
future.
-----------------------------------
Gary Bower ([log in to unmask])
Stanford Linear Accelerator Center
Stanford University
650/926-2460
|