Decumentation Review

This document is the output of the Documentation working group: Ivan

As requested in the WLCG monitoring consolidation meeting 18 July 2013, we attempt to answer the following questions regarding storage and aggregation:

• Are we doing things consistently for all of our applications?
• If we are doing things in multiple ways, is there a good reason for it?
• Are there any new technologies that would help us here?
• How long would it take to change?
• How would that impact the other layers?

Are we doing things consistently for all of our applications?

• Dashboard
  • what we use
    • distutil extension (using xsltproc) for generation of html doc pages (mostly not up to date)
    • Twiki (up to date documentation)
    • custom html pages
    • tooltips
  • what we have
    • developers guide how to work with dashboard framework
    • for the applications
      • user guides
      • admin guides
      • support guides (for shifters)
      • architecture/design overview of application

• SAM
  • what we use
    • Confluence
      • user guide
      • administrator guide
      • developer guide
      • development process
      • validation process
      • release process
      • operations and support
      • architecture overview
      • documentation per component
    • Sphinx
      • source code documentation

If we are doing things in multiple ways, is there a good reason for it?

Historical reasons

Are there any new technologies that would help us here?

Depends on the group strategy. Confluence can be integrated with JIRA and Bamboo as they all are Atlassian products, however a license has to be paid. Twiki is widely used at CERN, may be stay with Twiki. Sphinx is good for source code documentation.

How long would it take to change?

Few weeks should be enough

How would that impact the other layers?

Mostly transparent to other layers, fix some links from the Visualisation layer