Documentation Status

1. Documentation Status Stephen Burke RAL GridPP 15, 11th January 2006

2. Overview • Classifying the issues: • Documentation clients • Types of documentation • Formats • Topics • Existing documentation • Relations with other projects • Priorities • Improving the GridPP web site • Future work • Conclusions Documentation Status - GridPP 15

3. Clients • Middleware developers • Well-served by JRA1 internal documentation and web site • Sysadmins • Mostly well-served by LCG/SA1 installation docs • GridPP is providing a lot of data management/storage info • Architecture description would be nice • Try to encourage EGEE (SA3?) • Site “care and maintenance” guide • Would need input from experienced sysadmins • Users • Starting/developing/expert • Main focus of effort • GridPP users are all from HEP – but not all LHC! • Needs to be linked to experiment-specific docs Documentation Status - GridPP 15

4. Documentation types • Introductory material • Much available, but the Grid has a lot of new concepts: need feedback from real users • Read once (and read all) • Worked examples • Must be absolutely correct! • Short notes on specific issues • Easy to write, but hard to index • Detailed reference manuals • Usually long, hard to write and maintain • Howto/FAQ • Hard to structure and index • May be very situation-specific • Need to integrate with user support Documentation Status - GridPP 15

5. Documentation formats • Web page/site • Traditional, wiki, content management system • Good web site design is not trivial! • Knowledge base • Word/PDF • Powerpoint • Most talks not very useful as documentation • Text file • man page/inline help • Example files on disk • Different formats suitable for different purposes • Various maintenance/portability properties Documentation Status - GridPP 15

6. Topics • General Grid concepts, acronyms etc • Certificate/proxy/VO info • Much is UK- and/or HEP-specific • Also browser-specific • Some complaints about the existing CA docs • Basics • Job submission, data management, R-GMA, … • Monitoring, troubleshooting, error messages • Hardest to write • Detailed documentation • Must be written by experts • gLite manuals generally good • Experiment-specific documentation • Needs to come from the experiment! Documentation Status - GridPP 15

7. Existing documentation • There’s a lot of it about! But: • Written by many projects/groups/people • Scattered across many web sites • Often out of date (rapid rate of change) • Sometimes badly edited and/or inaccurate • Mostly written ad-hoc, no overall plan • Usually not reviewed • How to find it • google?! • How to judge accuracy/relevance? • How to fill gaps? Documentation Status - GridPP 15

8. Other projects • Many other projects involved • EGEE, LCG, national projects, experiments, Globus etc • ~ no dedicated manpower for documentation! But some groups try … • LCG EIS group • GGUS (user support) • NA3 (training) • JRA1 (gLite manuals) • SA1 (deployment docs, CIC portal) • National projects (INFN is good, ~all in English!) • Most experiments have poor/nonexistent Grid docs Documentation Status - GridPP 15

9. Coordination • So far mainly by EIS/ESC/GGUS • Main focus is user support • Many docs are LCG-oriented • LCG user guide - the best single document • GGUS list of docs: https://gus.fzk.de/pages/docu.php • GGUS should end up as a one-stop shop for users, but not there yet • EGEE has UIG (User Information Group) which should coordinate documentation, but ~ no manpower, hence little activity • May be better in EGEE 2 • GridPP must co-operate • Also have ~ no manpower • Avoid duplication • Feed documents back into common pool Documentation Status - GridPP 15

10. Priorities • New users are most important • Most users so far have been software experts • Steep learning curve • Need to get beyond “hello world” • GridPP web site should provide key information plus pointers to other sources • Provide an index, not an encyclopedia • Users at least need to know how to get help • Make comments to information providers • CA, LCG, EGEE, … • Try to get gaps plugged • Respond to feedback • Limited resources should be aimed where they are most needed • Liaise/coordinate with wider efforts Documentation Status - GridPP 15

11. Activity so far • Survey existing documentation, web sites • Directory, with comments, at http://www.gridpp.ac.uk/docs/doclinks.html • Improve user area on GridPP web site: • http://www.gridpp.ac.uk/deployment/users/ • Linked from GGUS • Pointers to external sources where possible • Minimise new material – must be maintainable • Organise by topic • UK-specific issues (e.g. CA) are a priority • First iteration complete – comments welcome • Talk to EIS/GGUS/ESC/UIG Documentation Status - GridPP 15

12. New documentation • Certificates etc • CA documentation has some problems • Comments fed back to CA • GridPP-specific guide on web • Introduction for new users • Troubleshooting guide • Difficult area, but something is better than nothing • Creating a new VO • Procedures still being defined • FAQs etc • Only for things not available elsewhere Documentation Status - GridPP 15

13. Next steps • Check and update web site, respond to comments • Check deployment web pages? • Perhaps commission specific documents • Site maintenance guide? Glue schema? • Review major external documents • More detailed documentation on web site? • Data management area maintained by Graeme Stewart • VOMS, job submission, R-GMA? • Need to limit to things which are really needed • Continue to liaise with ESC/UIG • Any requests? Documentation Status - GridPP 15

14. Conclusions • Lots of documentation, little dedicated manpower or organisation • Try to provide guidance through the maze • Need to improve co-ordination between projects • Documentation got many mentions in the EGEE meeting at Pisa • Experiments need better documentation of Grid interfaces • Maintenance is vital • High pace of change • A small volume of good documentation is better than a lot of poor, out of date documents! Documentation Status - GridPP 15