Final Report for Project 144 - Redevelop User Documentation

Approach

  • We needed to move existing end-user documentation from a number of sites.
    • Most of the documentation was held under www.inf.ed.ac.uk/systems/ but there was also more than expected on wiki.inf and dice.inf
    • We decided that the focus should be on moving pages from www.inf.ed.ac.uk/systems.
    • We decided that at least in the first instance, we wouldn't move wiki content but would use links. Such content was mostly moved later in the project, though some still remains.
  • Involve a small focus group of end-users in process representing academics, postgraduates, admin and researchers.
  • New site required better searching facilities.
    • The 'old' site had poor search facilities which was a concern raised by the focus group.
    • Decided to use the taxonomy module to allow pages to be tagged and therefore to create an index.
  • Supervised surfing session.
    • Carol went along to an IS session. She received positive feedback on our mock-up site.
  • Which CMS to use.
    • It took longer than expected to finally decide to choose drupal over zope/plone.
    • Roger designed the docproj theme to make it as close as possible to the University theme.
  • Flat structure or not ?
    • We originally planned to create a structure which attempted to match the menu on the LHS.
    • Later it was agreed that this did not provide any great value, was perhaps too rigid and therefore we chose to use a flat structure.
  • It was agreed that the old FAQ was unwieldy and needed a total revamp. We therefore created a new content type called 'FAQ' which allows a simple Question/Answer solution to the FAQ problem.
    • The intention is that the FAQ should only be used as a summary with links to fuller explanations.
  • Some guidance on authoring was required, including general guidelines on style and detailed guide on adding new content - see EditDocPages.
  • It was a requirement to have secure pages as not all content is suitable for public distribution. We decided to use cosign.
  • Although drupal has numerous modules, it was felt important to keep the number that we used to a minimum. We managed to limit this to:
    • cosign
    • ctools
    • date
    • diff
    • exclude_node_title
    • node_view_permissions
    • pathauto
    • print
    • token
    • views
    • views_data_export
  • We realised the need to review content regularly was essential so added a 'Last reviewed date' to each page with the intention that we could use views to generate reports indicating which pages are due for review.
  • We also realised the need for ownership of content and therefore created a 'Unit tag'. By default, the Unit tag is set to US-Unit.
  • We included a block to the right hand side of the home page which lists the 10 most recent changes. This should help users quickly review any updates to pages that are relevant to them. The block was originally included on each page but it was decided that it made pages look a bit cluttered and so should only be included on the home page.
  • Service documentation
  • Individual unit projects were created to update their own pages.
  • A week in February 2013 was earmarked as a Documentation week, in which much new content was created.
  • The little feedback we have received has all been good.
  • Documentation Editor (Chris) appointed.

Issues

  • Scope perhaps became too large.
  • Was difficult to motivate individuals to prioritise updating content over other work - Documentation week largely overcame this.
  • Lack of feedback at all stages through the process, even after the new site was announced.
  • Much more of the documentation needed to be updated than initially expected.
  • Much more documentation was missing than initially expected.
  • We should have created documentation projects for each Unit sooner than we did.
  • After initial activity of consulting with end-users project lost impetus while decision made on whether to go for zope/plone or drupal.
  • Cosign module rather primitive. Some remaining issues with email addresses and logout, but not considered critical.
  • How to maintain the documentation in a suitable state - appoint documentation person.

What's next

  • The System Alert block could be improved.
  • Our own 'internal' documentation is in need of a complete revamp.
  • Units cannot sit back - must continue to be focused on providing good end-user documentation and keeping existing documentation up to date.
  • There is still a certain amount of user documentation on the wiki pages and under www.dice.inf.ed.ac.uk which is linked to on computing.help. These need to be made into pages on the new site.
  • We have a documentation queue in RT where any requests/comments can be added.
  • We should pay particular attention when new projects come for sign off to ensure that relevant end-user documentation has been produced/updated.

The project took 25.5 weeks of CO effort and 15 weeks of CSO effort.

-- AlisonDownie - 18 Apr 2013

Topic revision: r16 - 26 Aug 2013 - 08:25:28 - AlastairScobie
 
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