0.2 Using the Workbook

Complete:
Detailed Review status

Contents

• Goals of this Page
• Philosophy of the Workbook
• Assumptions about your computing environment
• About the Workbook pages
  • Completeness indicator
  • Left hand menu
• Providing Feedback
• How to print WorkBook pages, chapters and the whole WorkBook
• Review Status

Goals of this page

The goal of this page is to show you how to get the most out of the workbook. The reader will learn what the various symbols and links on the workbook pages mean, what type of information they link to, who to contact about a given page, and how to provide feedback to the editors.

Philosophy of the Workbook

This workbook is intended to serve as a relatively stand-alone learning tool for new CMS members. It is designed to explain how to use the CMS SoftWare (CMSSW) application to analyze data. It should serve as a comprehensive tutorial. CMS plans to keep it current throughout the lifetime of the experiment.

The workbook is an effort to which any and all CMS members are encouraged to contribute. Identified content experts are asked to contribute content, which editors then organize and edit. Readers are strongly encouraged to provide feedback to the editors in order to help them improve the flow, content, accuracy and readability of the workbook.

The editing goals of the workbook include:

• Keep explanations brief, and provide links to supplementary information
• In general, the supplementary info should not be needed in order to complete the workbook (as a tutorial)
• Use a step-by-step format wherever possible
• Include specific tutorials for the various tasks
• Organization (table of contents) will evolve to accommodate content (form follows function).

Assumptions about your computing environment

The WorkBook instructions generally assume you're running CMS software on the CERN Public Login Linux system LXPLUS or on a remote system (with respect to CERN) that provides access to the CMS software releases and to the tools you'll need to develop your software, e.g., the CMSLPC cluster at Fermilab. In these environments, you can start work almost immediately. Local systems at other institutions may have different unix shells and different setups, and it is impossible to provide fool-proof instructions for all environments. For this reason, we invite institutions to provide information in Specific Information for Remote Sites and Institutions.

About the workbook pages

The CMS Workbook is a set of Twiki pages starting at https://twiki.cern.ch/twiki/bin/view/CMS/WorkBook. Each page states the goals for the reader, and most list informational sources used in compiling the content.

Completeness indicator

There is a progress indicator at the top of each page which gives the user a rough idea how complete the topic is from the author's and/or editor's point of view. Completeness is measured in terms of the content suitable for the Workbook, not in terms of anything and everything that could be written on the topic. The scale goes from empty (white) to complete (green) in six stages:
Complete:
Complete:
Complete:
Complete:
Complete:
Complete:

Beware that a Complete: topic may need reworking periodically and may change to some level of incomplete from time to time. Each page is reviewed periodically to make sure the content is still valid.

The latest review and/or modified date should appear in the Review Status at the bottom of the page, possibly with some explanatory text. The "responsible person" for the page should also be listed under Review Status and is a good contact if you have questions specific to that page.

Left Hand Menu

On the left hand menu of each WorkBook page, there are links to all the workbook topics. In addition, you'll find links to:

• a Glossary/Index of terms related to CMS, physics, CMSSW and GRID computing
• a Summary of Changes page which summarizes the workbook pages in terms of modification, review dates and content.
• a Site Map showing the pages under the workbook domain
• a Print WkBk as PDF link for printing chapters or the whole workbook to PDF (this is a customized printing format, and is different from the "Printable" and "PDF" buttons in the standard TWiki tool bar)
• a Contributors page which gives formatting guidelines for Workbook page writers and editors
• the CMS User Support page
• the Offline SW Guide containing the detailed information of all CMS software
• the Reference Manual containing the release dependent technical documentation such as class lists, brief description of content and purpose of each package and default configuration files and sequences
• the Online WB for instructions for shift and online work.

At the end of the left hand menu:

• a Page Template for creating new Workbook pages
• a Review for Printing page on which the editors keep track of the status of each page as they prepare for a mass printing, planned for a couple of times a year
• To Do List a notepad for keeping editors and contributors informed about work in progress and areas of the CMS workbook where contributions are most urgently needed

Providing Feedback

Presently the principal workbook editors are managed by the L2 Coordinators for User Support: Marguerite Tonjes and Sudhir Malik. You may email them with questions, comments, complaints, contributions, corrections, and so on, or you may use the CMS Workbook Documentation hypernews forum at https://hypernews.cern.ch/HyperNews/CMS/get/workbook.html and send your comments to a wider audience (this is recommended). If you're not yet a member of the CMS hypernews system, follow the instructions at https://hypernews.cern.ch/HyperNews/CMS/add-member.pl to join. Then you can access the CMS Workbook forum and optionally subscribe to it to receive by email all postings to the forum. The email gateway for this forum is: hn-cms-workbook@cernNOSPAMPLEASE.ch.

In addition to a discussion area, the CMS WorkBook hypernews forum also provides a public staging area for new workbook documentation proposed by CMS users. Please post suggestions for new workbook documentation - on all aspects of CMS operations - to this hypernews forum rather than editing the workbook pages without prior agreement from a workbook editor.

For those of you who do write and/or edit Workbook pages, please follow the guidelines in WorkBookContributors. This is necessary for ensuring a standardized look and feel in the browser.

How to print WorkBook pages, chapters and the whole WorkBook

See Print WkBk as PDF for printing parts (topics or chapters) of the CMS WorkBook, or printing the whole document.

---

Review status

Reviewer/Editor and Date (copy from screen)	Comments
MargueriteTonjes - 2 Mar 2018	updated for appropriate L2 Offline & Computing User Support people
CMSUserSupport - 18 Jan 2008	updated description of leftbar items
AnneHeavey - 14 Nov 2006	review and edits prior to end of 2006 mass printing
AnneHeavey - 20 Jun 2006	added "assumptions" section

Responsible: MargueriteTonjes
Last reviewed by: ScarletNorberg - 21-Nov-2015