Discussion Session 3 (Chair: Roger Jones)

"Grid Documentation" (What documentation is needed/missing? Is it a
question of organisation?)Panel Members: Stephen Burke, John Walsh, Tony Doyle, William Hay, Dave
Kelsey, Peter Love, Giuseppe Mazza, Robin Middleton, Ivan Hollins[recorded by: Tom Doherty]

Opening remark made by Roger Jones:

Survey undertaken by users board. Criticism about documentation. Resulting
in Stephen Burke being appointed documentation officer. Introduces SB.

Panel Introductions:

SB: Started post on 1st of September.
    Mainly concerned with - finding out which areas are important
                            for example sourcing a CA.
                          - what kind of documentation is suitable in
                            different circumstances for example a
                            wiki or a user manual.
                          - how to collect the information needed.
                          - how much detail is suitable.

RM: Hard to write good documentation.
    If a deployment document (for example) has been completed
    it is necessary to maintain/update it when necessary.
    FAQs are useful.

DK:  Who is responsible for writing each document is key, there
     may be a tendency for a developer or deployer to push it
     down their list of priorities. This leads to maintenance
     problems.
     User documentation is of course important but deployment
     documentation may be equally important.

JW:  Extra documentation needed for local customisation such as Grid
     Ireland.
     Found generally that documentation is lacking (but improving
     with gLite). Missing application development documents and
     best practices (for application development)
     Atlas LHCb support - no feedback.

GM: Documentation necessary for collaboration among grid sites

WH: More documentation necessary to support deployment?? set up.
    Should be easier to find.

TD: Defining the reader is important when writing documentation.
    There are three classes: (1) Users
                             (2) Deployment teams
                             (3) Middelware developers (usually well
                                 defined through APIs)

    Documentation is made simpler if delegation is well defined. There
    are certain places within GridPP to place documentation such as
    the Gridsite webpage and wiki.

IH: FAQ would be useful on CPU, memory spec's etc.
    For a new user - possible error messages and solutions would
    be useful also.

PL: LCG Administration - Good documentation available.

Discussion:

Could updates to documents be raised at meetings.
A mailing list specifically for document updates may be useful.
Competition between different solutions to one problem.
For all experiments - link in all documentation and give responsibility
to a line manager (for example) to oversee its maintenance.
What are the mechanisms or how do we find out what is inadequate within
a document - a document should be checked every few months to point out
its inadequacies => should a review process be set up by SB.
Roles and responsibilities should be established.
Important documents should be highlighted - and index of useful doc's
and what sources of documents are available may be useful.

Note: Comment made by Andrew McNab made in another discussion but
relevant to this one - Cut and paste useful support guides into wiki
- should this be made into formal documentation?