Documentation

From GridPP Wiki
Jump to: navigation, search

Good documentation improves the efficiency with which day-to-day tasks are undertaken and is essential for long-term project stability. The Ops-Team ensures that installation and deployment instructions applicable to the UK are maintained.

This area is co-ordinated by Andrew McNab (Manchester) and Stephen Jones (Liverpool).

Tasks

  • maintain GridPP web server infrastructure including wiki
  • maintain list of key documents (including web/wiki pages) that need to be maintained
  • record responsible person(s) for each key document
  • monitor document revision/rechecking status and flag out-of-date key documents
  • maintain list of required / desired documents and match with volunteers to write them.

KeyDocs document monitoring scheme

We have a monitoring page which shows the status of pages identified as Key Documents ("KeyDocs"). A list of these KeyDocs is maintained in the MySQL database, along with the core tasks area name. Key Documents outside the GridPP Wiki may have a placeholder page in the Wiki to monitor their status, and including any notes (eg "This EGEE document is now completely out of date!")

For each area the catch-all responsible person(s) are the co-ordinator(s) of that task area, who either maintain the pages in that category or delegate them. We have a Mediawiki template that must be inserted at the end of each key document with a specified responsible person for that document, the date of last review by that person, and the date the document was last judged to be accurate by that person. Dates must be in the format YYYY-MM-DD. If a document has never been accurate or reviewed, that must be indicated with the string "(never)".

The status note at the foot of this page was generated by a KeyDocs template similar to:

{{KeyDocs|responsible=Andrew McNab|reviewdate=2011-12-16|accuratedate=(never)}}

The presence of these templates and the dates are monitored at the level of the Wiki's MySQL database to dynamically produce a table of current document status on the fly. Reminder emails are also sent out for documents nearing (amber) expiry or already past it (red). The status table can be used in, for instance, the weekly Ops meetings to identify unchecked documents.

Required documents can be created as empty placeholders and only given an "is accurate" date when some minimum level of information set out in the request is met.

The Using KeyDocs page explains gives a user's view of the system, explaining how to add new key documents and maintain existing ones.

Ops Meeting Bulletins

For inclusion in the weekly GridPP Operations Bulletins there is a view of the KeyDocs page that includes a block of suitable wiki markup near the bottom.

This page is a Key Document, and is the responsibility of Andrew McNab. It was last reviewed on 2015-06-30 when it was considered to be 100% complete. It was last judged to be accurate on 2015-06-30.