Babar logo
Workbook HEPIC Databases PDG HEP preprints
Organization Detector Computing Physics Documentation
Personnel Glossary Sitemap Search Hypernews
Unwrap page!
Wkbk. Search
Wkbk. Sitemap
Logging In
Info Resources
Software Infrastructure
CM2 Introduction
Event Store
Modifying Code
Writing and Editing
Framework II
Find Data
Batch Processing
Advanced Infrastructure
New Releases
Main Packages
Event Displays
Contributing Software
Advanced Topics
Make CM2 Ntuples
New Packages
New Packages 2
Persistent Classes
Site Installation
Check this page for HTML 4.01 Transitional compliance with the
W3C Validator
(More checks...)

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

  • List the major sections
  • Partly fill in minor sections
The resulting document will become the front page and table of contents of the final document.

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 example jobs.

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 Collaboration

The detailed sections will not yet have been written, but the outline itself can be of use to new users.
  • 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.
You will have published as soon as the document is doing more good than harm.

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 of expertise.
  • 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

Asynchronous Items

The following other things to do can occur in any order.

Back to Workbook Front Page

Joseph Perl
Last edited by:
Jenny Williams

Last modification: 11 Mar 2001
Last significant update: 30 August 1999