Difference between revisions of "Documentation"
(Created page with "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 ...")
|Line 33:||Line 33:|
Revision as of 15:07, 18 August 2014
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).
- 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:
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. In the future, reminder emails etc may also be generated. 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.