Using KeyDocs

From GridPP Wiki
Revision as of 09:15, 19 September 2017 by Andrew Mcnab 40269d547a (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

This page describes how to maintain important documents in the KeyDocs documentation monitoring system that is part of the Documentation core task area.

All of the key documents correspond to a page in the GridPP Wiki. The page is either the document itself, or is a placeholder that links to the document elsewhere (eg an EGI document on an EGI website.) In either case a KeyDocs template must be placed at the end of the page containing the name of its responsible person within GridPP, the date on which its status was last reviewed, and the date on which is was last judged to be accurate.

We maintain a list of the titles of the all the key documents in the wiki, and the status of those documents is shown on the KeyDocs monitoring page. (This page is created from scratch every time it's viewed, so updates are visible immediately.)

Each key document is assigned to one of the core task areas and is the responsibilty of that area's coordinator(s), unless delegated to someone else.

Adding a Key Document to the system

If you are one of the task area coordinators, please follow this procedure if you want to a key document adding to the monitoring system. (If you're not a coordinator for that area, please ask one of the relevant coordinators to follow this procedure.)

  • Create the document as a page in the GridPP Wiki. Please choose the title carefully as it can't easily be changed in the future (it involves creating another page with the new name.) A single line document is enough at this stage. Please include the KeyDocs template described below, with your name to start with.
  • Mail with the URL of the page and the core task area you want to add it to.
  • If you want someone else to be responsible for the page, agree this with them and ask them to update the template with their name rather than yours. The name will be manually associated with their email address in the KeyDocs database so reminder emails can be sent correctly.
  • The person responsible can start writing / updating your page with the information it is meant to contain.
  • Once the KeyDocs database has been updated you should get a reply from Andrew and your page will be listed on the KeyDocs monitoring page.
  • Keep an eye on your document, updating the dates in the template when appropriate.

Reviewing vs accuracy

The system keeps track of when a document is reviewed and when a document was last judged to be accurate separately. The reviewing procedure makes sure we at least look at important documents every few months. Reviewing is about judging the document's status rather than updating the content. So you could say "I reviewed the document, and yes it's still totally inaccurate" but we hope as the person responsible for the document, you'll be able to improve it while you're there. While you review it, if you judge it be accurate you can record that in the system too, separately from its reviewed status (as the current date).

Maintaining a Key Document in the system

  • You can view the documents you are responsible for by going to the KeyDocs monitoring page and clicking on the Reponsible column to sort it by name, and then looking for your set of documents.
  • When the document is approaching expiry, the dates will go amber and then red. The monitoring page states the expiry periods in days. You should try to review documents before they go amber (or more frequently if appropriate for that document.)
  • When you have reviewed a document, just edit it and update the reviewdate in the template.
  • If the document is accurate you can update the accuratedate too. However, if the document is no longer accurate please just leave the accuratedate unchanged. Please do not change it to something like '(never)' - it was once accurate and the system can use that date to rank how urgent different reviews are.
  • Use the percentage value to indicate how complete the document is. Ideally documents will have specifications or outlines that they can be compared against to judge completeness. (The Discussion tabs for each document are useful for stating these.) If the document doesn't have a list of required components, please estimate it yourself. Round numbers like 10, 50 or 90 percent are fine and we're not trying to get precision figures. The percentages aren't yet displayed on each page, although they are listed on the KeyDocs monitoring page.
  • After you have updated the document, the KeyDocs monitoring page will be updated immediately. If any of the columns are shown as 'missing', you have probably made a syntax error in the template. Please go back and compare the syntax in the old and new versions using the History tab near the top of the page in the Wiki.
  • If you need to change the responsible person for a document, please mail so he can check that the email address corresponding to the new name is in the KeyDocs database.

Removal of documents

There is a process to remove a document from the wiki. If, in your opinion, a document should be deleted, add it to the Stale_documents page. This is reviewed periodically by a core task team member, and if consensus for removal is built in the operations meeting or via TB_SUPPORT, the document can be flushed.

A KeyDoc can also be downgraded, and kept as a standard document. If, in your opinion, a document ceases to be a KeyDoc, but you wish it to be retained in the wiki, then:

  • Seek consensus in the operations meeting or via TB_SUPPORT for the document to be downgraded.
  • Once "approved", remove the KeyDoc macro from the foot of the document.
  • Email Andrew McNab ( to inform him that the document has been downgraded. He will remove it from the database.

KeyDocs template format

The KeyDocs templates are similar to this in format:

{{KeyDocs|responsible=Andrew McNab|reviewdate=2012-02-17|accuratedate=(never)|percentage=50}}
  • The template must be placed at the end of the document, after all of the text and any categories.
  • Dates must be given in YYYY-MM-DD format, with leading zeroes on each of the three numbers.
  • responsible= reviewdate= accuratedate= and percentage= must be given in that order.
  • If a document has never been reviewed or judged accurate, then please give the date as (never) including the brackets.
  • The percentage complete values aren't meant to be precision figures: round numbers are fine. Please only include the digits (no % symbol etc.)
  • The responsible name must be the core task area coordinator or someone it has been delegated to.
  • Please do not leave the name blank or put (missing) etc, as each key document needs to be someone's responsibility at all times.

This page is a Key Document, and is the responsibility of Andrew McNab. It was last reviewed on 2017-09-19 when it was considered to be 90% complete. It was last judged to be accurate on 2017-09-19.