Thoughts on documentation

Panja LuukkaHelsinki Institute of Physics

Panja Luukka, Helsinki Institute of Physics 2

Introduction CMS Collaboration has decided to provide open

access to part of its data.In this context the data also includes software and

detailed documentation needed for the analysis in addition to the actual research data.

The open data pilot project with CSC is an excellent opportunity to find out which kind of tools and information CMS needs to provide with the data.

30/09/2013

Panja Luukka, Helsinki Institute of Physics 3

ChallengesThe obvious challenge is to define the information

that is needed for choosing and handling of the data.There is a lot of «silent knowledge» in the physics

analysis, which is not (or very randomly) docmented.We should find and document this critical

information to such an extent that also a non-physicist is able to understand what is important and why something is done in the physics analysis.

30/09/2013

Panja Luukka, Helsinki Institute of Physics 4

ChallengesThe computing software environment should be such

that it can be used without extensive knowledge of linux.Or at least the usage has to be documented in

detail.The most critical information should probably be part

of the analysis software package as people don’t usually read separate manuals..

30/09/2013

Panja Luukka, Helsinki Institute of Physics 5

Current statusThe software is developing towards more user-

friendly installation.However, still requires quite good computing

knowledge to get it running. Documentation is currently on the twiki pageIt is concentrating on the actual running of the

software (how to install and run etc.)No definitions of terminology, data selection criteria

etc. up to now.

30/09/2013

Panja Luukka, Helsinki Institute of Physics 6

Some open questionsWhere should the documentation be eventually

located?Twiki is a bit awkward tool for general public, even

though it is very useful now Should we also prepare a short «physics dictionary»

with the data and analysis tools..? E.g. Term «event» is not necessarily obvious to a

non-physicist and there are many similar words in physicist slang.

30/09/2013

Panja Luukka, Helsinki Institute of Physics 7

Some open questionsShould the software package include interactive

tutorial(s)? Would a user-forum be useful?

Surely there will be some problems and it is nice, if there is a forum in which you can discuss the problems

E.g. Something similar to Geant4 user forum might be relatively easy to create and keep up-to-date?

30/09/2013

Panja Luukka, Helsinki Institute of Physics 8

SummaryDocumentation is developing, but there are still

some open questions:Where should the documentation eventually be

located?What should it include in addition to data selection

criteria and installation instructions?Step by step tutorials?Definitions of terms and their use?

Should a user forum be created?

30/09/2013