Overview of Ganga documentation

1. Overview of Ganga documentation K. Harrison University of Cambridge Ganga Developer Days CERN, 9th-13th July 2007

2. Different types of documentation • Static documentation • Archived once written, with no further updating • Recycling sometimes possible • Journal papers, conference contributions, presentations at meetings, technical notes, funding requests, etc • Dynamic documentation • Continual updating needed to keep pace with development • Ganga website, tutorials, GPI reference manuals, Workbook, wiki pages, project plans and logbooks, etc • Focus in this presentation on parts of the dynamic documenation

3. Ganga website: background information • Site created 8th October 2002 by P.Mato • Ownership transferred 24th May 2007 to J.T.Moscicki • Initial content and many subsequent additions by K.Harrison • Some tinkering over the years, but site structure today remains close to the original • Two key choices made early on in website development • Keep design simple • Ensure pages load quickly, and can be viewed from any browser and on any web-enabled device • Ensure pages are readable when printed • Keep content local • Avoid relying on Ganga material being kept at other sites • Allow possibility of copying website files and having access to content when disconnected from the network • Wiki pages problematic in this context

4. Ganga website: content Website is gateway for accessing all Ganga-related material Users Developers • CVS code repository • Savannah • Tags form • Wiki pages • Tutorials • GPI reference • Workbook • Experiment-specificmanuals Historians, geographers, etymologists, etc Management • Planning documents • Logbook • Presentations • Conference contributions • Journal papers • Technical notes • Mail archives Consensus is that Ganga website has reasonable content, but design could be more visually interesting

5. Example websites for HEP-related projects Two common elements: banner and navigation bar  See suggestions for Ganga website from Y.Y.Li

6. Tutorials • Have tutorials in a numbers of formats and styles, with variations for ATLAS, LHCb and EGEE • Always possible to improve, but tutorials are already of a good standard LHCb - Edinburgh ATLAS - Munich ATLAS - Toronto January 2007 March 2007 April 2007 • Need to simplify maintenance, to ensure tutorials are kept up-to-date • Converge on a single format and style • Make tutorials more modular, encouraging reuse of material • Avoid references in body of tutorial to specific versions of Gangaand/or application software

7. Reference manuals for Ganga Public Interface (GPI) • GPI reference manuals provide documentation on classes, objects and functions available for specific configurations (i.e. sets of plugins) • As of Ganga release 4.3.1, GPI reference manuals can be generated using manual script • Output is html or plain text • Usage information available with: ganga manual --help • GPI manuals are created from information obtained using the Ganga help system, which relies on the code documentation • Formatting is performed using the pydoc module • Little flexibility with version of pydoc included in Python 2.2, but improvements with newer versions • GPI manuals for ATLAS and LHCb are now automatically generated as part of the release procedure, with links updated on the Ganga website

8. Requirements for code documentation • For the Ganga help system and GPI reference manuals to provide useful information, classes and functions need to include relevant documentation strings • Classes and functions: • Provide one-line description of functionality • Information used in index page • Provide multi-line detailed explanation of functionality • Can be omitted if one-line description is exhaustive • Classes: • Additionally provide documentation for all properties and methods • Suggested documentation conventions are described in a Python Enhancement Proposal (PEP 257) • Current status of GPI code documentation is summarised in a Savannah report (bug #27260) • Improvements welcomed from all developers

9. Ganga Workbook • Workbook is intended as an experiment-neutral reference covering all aspects of working with Ganga • Aims to be useful for users and developers alike • Still much to do for first version • So far essentially have a Scrapbook and a Workbook skeleton • Scrapbook collects material relevant for the workbook:http://ganga.web.cern.ch/ganga/scrapbook/ • Workbook skeleton defines format and structure:http://ganga.web.cern.ch/ganga/workbook/  Next step is to build up Workbook by importing content from Scrapbook Scrapbook Workbook skeleton

10. Wiki pages • Making information available through a wiki has attractions • Easy to produce web pages that look reasonable, without needing to know html • Good for collaborative work • Drawback in practice is that wiki pages tend to proliferate quickly but be poorly maintained • Of course, there are exceptions, and other web pages can suffer from similar problems • In Ganga development ,wiki pages have been particularly useful as a complement to e-mail • Discuss hot topics • Propose new ideas • Document experimental functionality • Good to continue this usage, but as development progresses would eventually expect key information to be moved to Workbook or other document • A wiki page might eventually be marked as obsolete, archived or deleted

11. Conclusions • A large amount of Ganga documentation already exists, but there are gaps and areas needing improvement • Something for everyone to do during sessions dedicated to Documentation Writing • Continued effort necessary to ensure documentation remains up-to-date • Work model for developers needs to be along the lines of: • Implement • Document • Write test case