Developing Documentation for art

This wiki holds information and working notes needed to develop documentation for art. Most new art users will be introduced to art via the workbook and most of this page is focused on three things: What is the big picture? Where does the workbook fit into the big picture? What does the workbook look like?

The big picture of the art documentation suite, including where the workbook fits in the big picture, is available in a power point presentation. The most recent version is version 5 which includes information added following the March 27, 2013, meeting between Anne, Ruth, Rob R and Rob K.

These notes will present what the final documentation product should look like, even though it may take a long time to reach that goal. Once this is established we can discuss short term goals for the first release.

For the first prototype we presume that the workbook exercises will be run by someone who will log into a GPCF machine and run them there. We very quickly want to move past this so that people can download what they need and run them on their own machine. A frequently heard criticism of art is that it can only be used at Fermilab; we need to break this.

For historical record, the Presentation shown at the January 23, 2013 Startup Meeting can be found in the "Files:" section of the art-workbook redmine site.

Major Goals

At present the experiments using art have mixed their art documentation in with their documentation of their experiment specific software. This makes it difficult to share art documentation between experiments; it leads to needless duplicated effort and it leads to mixed quality of art documentation across the experiments.

  1. Eliminate unnecessary duplication
  2. Where necessary, improve the quality of existing material
  3. Provide a Table of Contents and indexing to make the material easier to navigate.
  4. Provide well structured environment for new material.
  5. Provide a better introduction to art for new projects that are considering art for their framework.

Existing Material

There is already a lot of Existing Documentation that can be mined for both content and ideas.

The Overall Structure

In the present design, the art documentation has three main elements: an introductory section, a workbook and a reference manual.
These are sketched in more detail in the wiki page about Overall Structure

Draft outlines

There are two parts to the workbook.

  1. A few "Hello World" exercises to introduce ideas like, EventId, input files, changing input files, changing number of events, parameter sets, the methods of a module and so on.
  2. Some exercises based on a toy detector that is rich enough to illustrate the remaining features without getting lost in the details of the detector. We need to decide Which Detector to use.

Here are some draft outlines. They do not all (yet) respect the two parts mentioned above.

  1. Adam circulated a draft outline for the workbook by email. See Adam's Outline.
  2. Rob's Outline for the workbook, adapted from the Mu2e Workbook.
  3. Rob's Reference Manual Outline

Getting Started

The first prototype of the workbook is deployed on the mu2e machines. I have prepared some Getting Started instructions; these will likely evolve with time.

Role of the Editor and Tech Writer

  1. Deploy and maintain the outline in the chosen technology.
  2. Integrate existing material into the site
    1. This may involve significant rewrites to remove experiment specific pieces. # Test that the exercise work as described
  3. Provide a consistent look and feel across the project.
  4. Bring the lessons learned from CMS
    1. Ask CMS for any feedback they have from their existing "Pre-Exercises" ( The art workbook is close to the Pre Exercises defined by CMS ). # Learn how much ongoing effort CMS put into the "Pre-Exercises"
  5. Identify and keep records of
    1. Undefined terms and ideas # Missing link targets # Link targets that are only stubs # Existing material still to be incorporated
  6. Feedback to Rob K about what is working and not working (from the editor's point of view).
  7. Work with Rob K to keep pressure on people to produce missing content.

Needed Bugfixes and other issues

  1. buildtool does not ignore .# emacs temporaries. Maybe it should prompt? Maybe the default should be to stop with an override option?
  2. Same issue for temporaries from other editors
  3. Deletion of .root and .log by buildtools -c
  4. How can a user save their work?

Nasty things to warn about:

  1. What's wrong with this:
      std::vector<T> v;
      // ... Fill v ....
      // Loop over all pairs of tracks.
      for ( size_t i=0; i<v.size()-1; ++i ){
        T const& t1 =;
        for ( size_t j=; j<v.size(); ++i ){
          T const& t2 =;
          // do stuff with t1 and t2.

    If v happens to be empty, the test i<v.size()-1 passes because v.size()-1 is actually the maximum unsigned integer! The solution is to write the first line of the double loop in one of the following two ways:
      for ( size_t i=0; i+1<v.size(); ++i){ 
      // or ..
      for ( int i=0; i<int(v.size())-1; ++i ){
  2. Given:
       CLHEP::Hep3Vector       p;
       CLHEP::HepLorentzVector q;
       double pMomMagnitude = p.mag();
       double mass       = q.mag();
       double qMagnitude = q.vect().mag() 

    It is a common mistake to forget about the .vect() on the last line and compute the mass of a 4 vector when you really meant to compute the magnitude of its 3-momentum.