Review of user documentation

At the Operational Meeting of 9th December 2009, a lengthy discussion was had about the future plans for our computing documentation. (This was in the context of the 'Review of user documentation' project (devproj #36), and the two papers - discussion paper, and summary report - which that project had previously produced.)

Most of our CO's and CSO's were present at this discussion: the attendance list was as follows:

Ross Armstrong, Toby Blake, Lindsey Brown, Neil Brown, Roger Burroughes, Chris Cooke, Carol Dow, Alison Downie, Ian Durkacz, Graham Dutton, Stephen Quinney, Iain Rae, Gordon Reid, George Ross, Alastair Scobie, Craig Strachan, Simon Wilkinson

Not present were:

Scott Barr, Richard Bell, Tim Colles, Sheila Gardner, Ewan Grant, Jennifer Oxley

The following decisions were taken:

  1. The Wiki is not defended by anybody as a permanent home for documentation: it's only become used as frequently used as it is in the absence of other homes for documentation, and because it's easy.

  2. We will repurpose the website, and use it as the container for virtually all (*) of our computing documentation. Documentation content currently located in other places (e.g. the DICE Wiki; the Informatics website; the current DICE website) will be migrated.

    The format of the name matches the format of the names of the websites of all of our institutes, namely www.<institute> It also maintains existing practice, and the existing identification of the School's computing section with the DICE 'brand'. It is not intended to imply that the website solely documents the DICE project per se.

    (*) 'Virtually all': the intention is to integrate all documentation which is currently distributed over the existing DICE website, the Wiki, etc. It is not the intention to mandate that all documentation must be located at the new site. Specifically, for example, the website will continue to be the home for all pure 'LCFG' documentation; likewise for other similar cases.

  3. will therefore also be used for externally-facing documentation - so it has an additional role of advertising/advocacy for the DICE 'brand' and all related work that we are doing. It should have sub-sections which link to active projects, etc.

  4. The intention is to break as few as possible of the links within the current DICE site which might be referenced from outside, e.g. (Such links might be retained by redirections, where necessary.)

  5. Zope/Plone will be used as the CMS: since we have decided that this is the CMS which is to be used by all institutes here, we should use exactly the same technology for our own purposes.

  6. A human editor will be appointed/named. He/she will have overall control of the structure and content of the website. He/she also will also have responsibility for the overall maintenance of the documentation website.

  7. We will aim to reauthor our user documentation first. This should, among other things, give a real test of the use of Zope/Plone.

  8. It will be important to produce an overall structural plan/information architecture before we begin.

  9. There are issues of Zope/Plone workflow we need to get sorted out. Iain Rae emphasised that it's important to try to get this right first time: subsequent changes to the workflow may mean that the entire website has to be rebuilt.

  10. It might be useful for people to attend 'how to author for Plone' courses; there might be a chance to share costs of this with other interested parties throughout the University. Such courses need to be investigated.

Other comments

  1. Simon Wilkinson questioned the contention (in the above-mentioned summary report) that "we should not mandate how and when any such documentation is read: it should be as platform- and media-independent as possible." His view is that authoring the equivalent material for different media might generally require different approaches.

-- IanDurkacz - 02 Feb 2010

Topic revision: r5 - 01 Mar 2010 - 17:41:08 - IanDurkacz
This site is powered by the TWiki collaboration platformCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
This Wiki uses Cookies