This wiki serves as a draft structure for the discussion of Documentation, Testing and Support issues during the GANGA Developers' Day.

Documentation

Review of online documentation

The amount of online help available for Ganga commands and classes is a bit variable. For example, help(Job) gives a lot of useful information, but help(jobs) doesn't tell the user much more than dir(jobs). Aims of the review could be:

• identify the items with little or no online help, and encourage the relevant developer to write some documentation;
• understand if the existing online help is at the right level for users or if it's too technical.

UE: The agreement is that help on each class should give the following information:

• A one line explanation
• An example of usage
• More detailed explanation (if required)
• Documentation of properties

For the config file adopt Kuba's proposal of using doc strings when declaring default values. The interaction with the config object should be improved so it supports tab expansion of setting properties like config.LCG.VirtualOrganisation='lhcb'

Auto generation of documentation from code

We will revisit this topic to ascertain if indeed we should have a policy to embed suitably formatted docstrings that will provide automated documentation generation software with useable content.

• Estimate amount of work needed to add rigid docstring syntax to existing code
• Identify level of detail required i.e. how much to write, which methods to describe.

UE: Kuba will try to use doxygen and from the result of this we will judge how to continue. The old HappyDoc documentation will be discontinued.

Ganga User Manual

There is (I believe) concensus that there is a significant amount of information out there on GANGA but there is a glaring need to organise them properly and bring them all up-to-date. A (single) printable document has been suggested (by Dietrich Liko). Someone will need to be appointed as editor to coordinate this effort.

• Identify format of developer contributions (e.g. plain text, Twiki syntax, RST syntax)
• Choose format of online user manual documentation (e.g. Twiki)

UE: The separation of general, ATLAS and LHCb documentation should be slightly changed:

• A general documentation. This should be very detailed. the formatting will still be done in Latex, with both an html and a PDF version.
• An ATLAS and LHCb documentation that will act as a start-up guide. These should be readable without referring to the general documentation for basic work. For more details on specific Ganga functionality refer to the general manual (like how the token monitoring work). The format (Latex, Wiki, ??) is free but it should be possible to create PDF versions as well.

Documentation update frequency

This is done on and ad hoc basis at the moment. With an increasing user base (and if we want to keep it that way) we need to agree on documentation update frequency. We need to add documentation update as part of the Ganga release cycle. Possible documentation update frequency:

• every X and Y change for each Ganga version X.Y.Z
• update of a single webpage (info from release notes) for every Z change.

Other minor documentation issues

• Help documentation is currently not accessible from the GUI. This is not ideal. The discussion on the online user manual will help determine how to move forward on this issue. Recent GUI tutorial material (ATLAS only at the moment) may be added as well.

Testing

There are several areas we can discuss here:

• Experiences with testing framework and suggested improvements.
• Feature wish list

UE: We should create a form for submission of new tags. This one will have fields for test cases as well. For new features the test cases should follow the SavannahXXXXX.gpi naming convention.

Support

There is some overlap here with the promotion of GANGA.

UE: We should create separate support mailing lists for LHCb and ATLAS in HyperNews. Ulrik will create this for LHCb and Dietrich for ATLAS. Continued mails to the project-ganga list will be redirected to the HyperNews from each experiment.

User support

User support so far has been fairly ad hoc, and has typically involved one of the following:

• a user submits a help request in electronic form - an e-mail either to an individual developer, an e-mail to one of the Ganga mailing list, or a Savannah report;
• a user gets help from the Ganga developer who's just down the corridor. Such help rendered should be documented as well.

The level of support provided has been good so far, but at least partly because there are few users. We need to understand how to cope in the case of many users. (In particular, the second method above doesn't scale well!) Questions to be addressed might include:

• do we need a specific person to take responsibility for dealing with help requests on a week-by-week basis?
• do we need a dedicated project-ganga-support mailing list?
• do the experiments have software support structures with which Ganga support should be integrated?
• could error messages be made easier for non-experts to understand, so that users have more chance of sorting out problems themselves?
• FAQ compilation (should not simply bea digest of e-mail responses) by developer on weekly rota?

Tutorials

We should perhaps review existing tutorial material, identify areas where improvements are needed, evaluate the success of tutorials held so far, and discuss plans for tutorials in 2007.

• Twiki updates. GangaAtlas tutorials are ATLAS version sensitive.
• There are more and more institutes will want to use the tutorials we provide to teach their local users.

Webpage redesign

Here there are two main aspects to consider:

• Content
  • What needs to be added? E.g. Version summary, current release information
  • Is there anything that should be removed?
  • Can the web pages be better organised?

• Look
  • The current look is defined by a simple style sheet. By changing this, a more exciting look can be obtained across the web site.

Publication

We should discuss writing a peer reviewed journal paper on Ganga. It should be maybe 20 pages long and contain an overview of the design goals, the architecture, the plugins and some use cases. It could take one of the recent conference proceedings as a starting point. the merits of a publication would be:

• Adding to the list of peer reviewed journal papers for all of us.
• Be a "high quality" reference for Ganga in the future.
• force us to have explain well what we have done.

The obvious disadvantage of this would be the time it takes to write and pass through the review process.

Where should we be aiming to publish? Possibilities include:

• Computer Physics Communications
• Journal of Physics G: Nuclear and Particle Physics
• Nuclear Instruments and Methods in Phyics Research A
• IEEE Transactions on Nuclear Science
• non-physics journal.

UE: General agreement on a publication. Ulrik will be the editor. One of the first two journals are optimal. A time line is:

• March 1 : First draft
• May 1 : Final internal draft
• June 1 : Submission to journal after experiment review

---

• AlvinTan - 01 Nov 2006
• UlrikEgede - 03 Nov 2006
• AlvinTan - 01 Dec 2006
• UlrikEgede - 05 Dec 2006