CMS Software Documentation Project Plan

The CMS Offline Guide The CMS Offline WorkBook

PROJECT ANALYSIS

How did is all start?

• Some CMS Software documentation existed but there was no central access point to it
• The existing documentation was inconsistent in regards to its content
• There were no common guidelines for creating documentation
• No common naming system existed
• CMS Software users could not locate documentation or there were no documentation to refer to

What is the status today?

• More CMS Software documentation has become available but still the documentation is not all-inclusive and the format is not unified
• There are common guidelines for creating documentation but it is not followed and/or its importance is not understood
• The structure of CMS Twiki pages needs to be improved so that the finding of relevant information is easy and fast
• CMS Software documentation is still scattered to different locations
• Supervision of documentation is limited (reviews do not take place very often)
• Kati Lassila-Perini has initiated a comprehensive CMS software documentation review
• There are still shortages in all-inclusive CMS Software documentation

PROJECT DEFINITION

What needs to be done? (Theory)

• Evaluate the current status of documentation
• CMS Software developers and responsibles need to take initiative to start/improve/complete/review their documentation
• Provide CMS Software developers and responsibles clear instructions about what to include and what not to include in the documentation
• Provide CMS Software developers and responsibles training and guidance on how to fulfill the goals of the documentation
• The Software documentation needs to be created so that the documentation readers (software users and developers) can locate the relevant information easily and fast (e.g. what is in the data, how it has been constructed and how it can be accessed)
• Once documentation is available, evaluate that the previous statement is true
• Expand the supervision of the CMS Software documentation and the CMS Twiki pages so that the information inside is kept up-to-date and according to given standards

How to do it? (Knowledge)

• Set the metrics for determining when the documentation meets all the specified requirements and when the documentation can be considered as accepted (to be put on the Twiki pages)
• Discuss with the groups to set clear responsibilities among project members and set immediate goals for each group individually
• Set a review for documentation after documentation is available
• Conduct a test where software users/developers test the documentation to see if the documentation includes all the necessary information and that it can be located easily
• Follow-up meeting to identify the missing areas to be completed
• Use of specialist (Leena Salmi) to gain knowledge and experience

GOALS OF THE PROJECT

• Embed documentation creation/maintenance/review into the routine tasks of any software developer or user
• Setting up a comprehensive starting point to anyone who is new to software
• Creating good quality documentation
• Coherent Twiki pages
  • Set a clear naming policy for Twiki pages – all information needs to be easy to find and needs to be according to certain set of guidelines
  • Set a clear guideline for Twiki content structure
  • No private pages should be linked to / used on CMS Twiki site
• Documentation guidelines
  • Clear instructions for documentation creation, which will state what “good quality” documentation consists of
  • Documentation needs to be clear to understand
  • Documentation needs to include all relevant information (it does not need to be all-inclusive but it needs to have information about where to find additional information)
• Supervision
  • Ensure everyone provides some level of documentation
  • Conduct regular reviews to ensure documentation is up-to-date and it meets the specified requirements
  • Provide assistance in any stage of the documentation life (from creation to maintenance) if required

PROJECT INTEREST GROUPS

Software users

• Need to be able to locate information and instructions easily
• Need to be able to make data analysis independently

Software developers

• Need all-inclusive reference point, which they can use to find information
• Need guidelines for creating documentation when necessary

Documentation writers

• Need clear guidelines for creating documentation

PROJECT ORGANIZATION

Ordering Entity

• Kati Lassila-Perini from the CMS user support
• Kati is organizing the project and leads the CMS documentation planning in general

Project workers

• Person to work with KLP full time or 50% to help organize and supervise the project
• Leena Salmi
  • a specialist who is a non-CERN person providing expertise to the project content and implementation
  • will help conduct a user usability test
  • will conduct a research on information search and findability

Software groups

• Definition of who will be involved in the project
  • main contacts for during and after the implementation of the documentation project
  • who will be responsible for actual documentation writing
  • who will test the documentation once it is completed
• Will participate in reviewing the current status of documentation
• Will set goals of what needs to be done

COMMUNICATION

• Send regular project status updates to CMS Software users
• Send individual project status updates to each Software group

PROJECT IMPLEMENTATION

Week 1 (from 3 to 7 November 2008)

• Step 1: Define questions to be asked from the project specialist Leena Salmi

Week 2-4 (from 10 to 28 November 2008)

• Step 2: Define the current status of documentation
  • Take new software users and test documentation usability and information findability
• Step 3: Review and update instructions/templates for documentation creation

Week 5-7 (from 1 to 19 December 2008)

• Step 4: Determine the responsible person from each software group, i.e. the group's documentation project manager (GDPM), who will supervise and manage the project
• Step 5: Heuristic evaluation of each main page with GDPM, dates and names for POG (http://www.doodle.com/participation.html?pollId=s479kvkg5vcmww9i):
  • POG
    • Vertex: Thu 8 Jan 9:30 Thomas Speer
    • TAU + Particle Flow: Fri 16 Jan 9:30 Letizia Lusto
    • JetMET: Tue 20 Jan 13-17 Peter Schleper (+evt. Mon 19 morning)
    • B-tag: Thu 22 Jan 9:30: Wolfgang Adam
    • Muons: Fri 23 Jan 9:30: Slava Valuev
    • Tracks: Tue 17 Feb 9:30: Giuseppe Cerati
    • egamma: Tue 24 Feb 9:30: Matteo Sani
  • offline group
    • physics tools: Thu 12 March 10:00: Benedikt Hegner, Sudhir Malik
    • PAT: Thu 2 April Roger Wolf, Frederic Ronga
    • Sim & gen: May 7, 8, Julia Yarba
  • PAGs
    • Fwd PAG Grzegorz Brona (@fuw.edu.pl) tue 5 March 10:00-
    • EW Jonathan Efron Tue 28 April 13-16
    • Exotica PAG Sarah Eno Tue May 5 14:30-17:30, reschedule the week after
    • SUSY Gheorghe (Jim) Lungu Tue May 12 15-18
    • Top PAG Roger Wolf
    • QCD
    • Higgs Nicola de Filips physics week
    • B
    • HI
• Step 6: Create a summary of what is missing (if anything) in the current documentation and analyze results from Step 2
• Step 7: The GDPM creates presentations/summary to be held for each specific group using the results from Step 6
• Step 8: The GDPM
  • gathers up a group of people who will participate in the project: documentation writers, documentation users (who will test the documentation when it's created), software developers etc.
  • sets up an appointment for the project start-up meeting.

XMAS HOLIDAY

Week 8-11 (from 5 to 30 January 2009)

• Step 9: The project start-up meeting with the GDPM and the group's other project members defined by the GDPM
  • Set up project goals for each software group
  • Set clear areas of responsibilities for each group's project members
  • Set up a schedule for the project implementation (documentation creation)
  • Set up an appointment for next project meeting – review of documentation during the project weeks 12 and 13
• Step 10: Documentation creation by each software group
  • Provide assistance if needed
  • Each group needs to hand-in a progress report in the middle of the documentation creation stating the progress of the project so far and stating if the schedule specified in Step 9 is still valid

Week 11 after each software group has completed Step 10 (from 2 to 6 February 2009)

• Step 11: Documentation review by the user support
  • Determine the status of the documentation and if it meets the specified requirements

Week 12-13 (from 9 to 20 February 2009)

• Step 12: Follow-up meeting with each software group individually
  • Let each software group present what they have done
  • Present your own results from Step 9
  • Determine the need for further actions
    • More work needed on the documentation – implement Steps 10, 11 and 12 again
    • Documentation is acceptable and the work can be taken to next level – move to Step 13

Week 14-21 (from 23 February to 24 April 2009)

• Step 13: Conduct a user usability test with the help from Leena Salmi
• Step 14: Summarise and analyse results from Step 13

Week 22 - Project closure (from 27 April to 1 May 2009)

• Step 15: Hand in the results and define the need for further actions
  • Hold a presentation in a joint CMS meeting

PROJECT FOLLOW-UP

• Ensure that documentation is kept up-to-date by conducting review e.g once a year
• Update the contact information for each group on a continuing bases
• Allow users and software developers to give feedback

-- PirittaHeikkila - 09 Oct 2008