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

2. 9th July 20072/11 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. 9th July 20073/11 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. 9th July 20074/11 Ganga website: content Website is gateway for accessing all Ganga-related material Users Tutorials GPI reference Workbook Experiment-specific manuals Developers CVS code repository Savannah Tags form Wiki pages Management Planning documents Logbook Historians, geographers, etymologists, etc 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. 9th July 20075/11 Example websites for HEP-related projects Two common elements: banner and navigation bar  See suggestions for Ganga website from Y.Y.Li

6. 9th July 20076/11 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 January 2007 ATLAS - Munich March 2007 ATLAS - Toronto 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 Ganga and/or application software

7. 9th July 20077/11 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. 9th July 20078/11 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)PEP 257 Current status of GPI code documentation is summarised in a Savannah report (bug #27260)bug #27260 Improvements welcomed from all developers

9. 9th July 20079/11 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/ http://ganga.web.cern.ch/ganga/scrapbook/ Workbook skeleton defines format and structure: http://ganga.web.cern.ch/ganga/workbook/ http://ganga.web.cern.ch/ganga/workbook/  Next step is to build up Workbook by importing content from Scrapbook ScrapbookWorkbook skeleton

10. 9th July 200710/11 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. 9th July 200711/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