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