Workbook for BaBar Offline Users - Development Process
The Workbook should be written by a group of four or more people who
could be graduate students, post docs, or programmers. A group of
this size provide useful feedback to one another. A mix of new and
experienced software users is helpful. In BaBar, the most prolific
writer was a Physics BA hired specifically for this task with no
previous HEP collaboration experience.
Graduate students who have participated in the Workbook projects of
SLD and BaBar have received very great appreciation and prestige for
their contributions. Their work has been perceived as one of the most
important service jobs in their collaborations.
The Workbook is a major undertaking (approximately one person-year
integrated effort), but if it is done according to the following
process, it pays off before the most time consuming part of the work
has even begun.
Phase 0: Set the Scope
- Who is the audience?
New users of the BaBar offline analysis system.
- What is the beginning user assumed to know?
The user is assumed to be comfortable with computers, but is not
assumed to know any one particular operating system. The user is
assumed to have a knowledge of Physics consistent with an incoming US
Physics Graduate Student.
- What is the scope of material to be taught?
Everything the user needs to know to perform offline analysis jobs.
Phase 1: Initial Outline
The resulting document will become the front page and table of
contents of the final document.
- List the major sections
- Partly fill in minor sections
The Quick Tour section should pull the user in. This one section only
should direct the user to type input cookbook style, without full
explanation. Later sections should cover this material through
multiple passes to greater depth.
Phase 2: Input from Generalists
- Solicit help from software experts (generalists) and new users to
refine the results of Phase 1.
Have met with and incorporated comments from the following people:
- Neil Geddes
- Teela Pulliam
- Daniel Azzopardi
- Bill Lockman
- Tom Glanzman
- Paolo Palazzi
- Paul Raines
- Charlie Young
- Walter Toki
- Bob Jacobsen
- David Quarrie
- John Bartelt
- Abi Soffer
- Bob Wilson
- Paul Harrison
- Review the outline for completeness and for order of introduction of concepts.
Phase 3: Outline Initial Set of Example Jobs
- Outline the set of example jobs.
The example jobs need not be complete, but should serve to show us the
order in which we will introduce commands.
- Revise the order of introduction of concepts to match outline of
Phase 4: Contributions from Experts (see reviewers.html)
- Write stubs of major sections
initially just populating them with a set of bullet points
and a set of pointers to existing documentation.
- Assign each major section to an expert in that section's content
asking that they complete the relevant list
of bullet points and correct the relevant list of existing documents.
- Is there sufficient buy-in from the experts to support the project?
- Assess manpower/ability to complete the Workbook project
If the previous step does not show readiness of experts to contribute
their time to this project, consider whether the actual Workbook
writing can proceed. Hire if necessary and possible.
Phase 5: First Useful Release
- Reformat/Refine Contributions from Experts refining them to
achieve a consistent style. Place the links to related documents into
more finely grained structure.
- Release the Workbook as Preliminary but Already Useful
You Now Already Have the Most Useful Document in the
The detailed sections will not yet have been written, but the outline
itself can be of use to new users.
You will have published as soon as the document is doing more good
- It suggests what topics users should learn in what order.
- It lists many of the most commonly used tools and commands.
- It provides links to currently available documentation that
appropriate experts have declared to be worth reading.
Phase 6: The Rest of the Job
This part of the slow part of the work, but if the outline has been
done correctly, different sections of the Workbook can be completed by
different authors without requiring continual interaction. The
outline and the stubs of the sections provides enough detail to tell
each author what is to be handled by the other sections.
- Authors get to assume everything before their section has already
been covered. This enables them to concentrate on their specific area
- Excerpt from Existing Sources, cutting and pasting relevant
passages from existing documents into the new document.
- Add Detailed Example Code
A well connected set of examples will be interspersed into the
explanations. For example, after a document explains how to create
directories, we would have the user do a mkdir to create the release
directory that they will later use.
For example, after a document explains how to create directories, we
would have the user do a mkdir to create the release directory that
they will later use.
As another example, after you show how to find a k short with the full
data, the next section might show how to get the same result from a
micro data summary tape.
- Detailed Writing
- Update parts taken from old documents
- Fill in new content
- Achieve a consistent style
The following other things to do can occur in any order.
Last edited by:
Last modification: 11 Mar 2001
Last significant update: 30 August 1999