SLAC PEP-II
BABAR
SLAC<->RAL
Babar logo
Workbook HEPIC Databases PDG HEP preprints
Organization Detector Computing Physics Documentation
Personnel Glossary Sitemap Search Hypernews
Unwrap page!
Wkbk. Search
Wkbk. Sitemap
Introduction
Non SLAC
HOWTO's
Introduction
Logging In
QuickTour
Detector
Info Resources
Software Infrastructure
CM2 Introduction
Unix
OO
SRT
Objectivity
Event Store
Framework
Beta
Modifying Code
Writing and Editing
Compiling
Debugging
Analysis
Framework II
Analysis
Find Data
Batch Processing
PAW
PAW II
ROOT I
ROOT II
ROOT III
Advanced Infrastructure
New Releases
Workdir
Main Packages
Event Displays
Gen/Sim/Reco
Contributing Software
SRT and CVS
Coding
Advanced Topics
Make CM2 Ntuples
New Packages
New Packages 2
Persistent Classes
Java
Site Installation
Check this page for HTML 4.01 Transitional compliance with the
W3C Validator
(More checks...)

Workbook for BaBar Offline Users - Origins

1994: SLD

Lines Outside our Doors

The workbook approach was first conceived in 1994 to solve a problem for the SLD collaboration. The main offline software experts for that collaboration occupied a single hallway at SLAC. As the collaboration began to take data, near permanent lines formed outside the doors on that hallway. Offsite collaborators suffered even more frustration than those waiting in the lines.

New Users Task Force

Joseph Perl was asked to lead a task force to find a solution to this problem. The task force was staffed with a mix of new and experienced graduate students and post docs.
  • Physicists learn by copying the analysis jobs of other physicists.

Solution: the Workbook Approach

  • Create a Workbook, a connected series of example jobs interspersed with commentary about the software.
The term Workbook here comes from the commonly used term for the books of example problems that American physics students work through in their courses.

Six months later, with the release of the Workbook, the lines outside the doors disappeared and collaborators on and off the site reported satisfaction.

New Users Workbook became Offline Users Workbook

The name of the document was soon changed from "New Users Workbook" to "Offline Users Workbook" to reflect its significant usage by experienced users as well as new ones.

1998: BaBar

Essentially the Same Problem

Since the BaBar collaboration's programming base is far more geographically distributed than was SLD's, there were no visible lines outside any doors, but the frustration of new users was evident in phone calls, emails and newsgroups.

Documentation, Communication and Information Task Force

Paolo Palazzi was asked to lead a task force to find a solution to problems of documentation, communication and the exchange of information in BaBar. The task force was staffed with a mix of physicists and programmers. The frustrations of new users quickly arose as a major issue. Even where documentation did already exist, the new users had no way to know which documents to read, which archaic ones to ignore, what to learn in what order, and so forth.

Solution, the Workbook Approach

Since Joseph Perl was on the task force, a Workbook was again proposed. Increased new user satisfaction was again the result.

It's Nothing Special

There is nothing particularly innovative about the Workbook approach. Similar tutorials are in existence elsewhere in the software world. For example, between the creation of the SLD Workbook and the BaBar one, Sun introduced an excellent Java Tutorial designed along similar lines.

Despite being the natural solution to such problems, none of the four large HEP collaborations that Joseph Perl joined (MKIII, MKII/SLC, SLD, BaBar) had this solution before he introduced it. We tend to focus on shorter term goals. Only later do we realize how much user frustration and waste of developer time goes into less formal tutorial approaches.


Back to Workbook Front Page

Author:
Joseph Perl
Last edited by:
Jenny Williams

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