Final Report for Project 144 - Redevelop User Documentation


  • We needed to move existing end-user documentation from a number of sites.
    • Most of the documentation was held under but there was also more than expected on wiki.inf and dice.inf
    • We decided that the focus should be on moving pages from
    • We decided that at least in the first instance, we wouldn't move wiki content but would use links.
  • 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.
  • Involve a small focus group of end-users in process representing academics, postgraduates, admin and researchers.
  • 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 (although this is no longer used)
    • 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.
  • The little feedback we have received has all been good.
  • Documentation Editor (Chris) appointed.


  • Scope perhaps became too large.
  • Lack of motivation.
  • 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.
  • 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 which is linked to on 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 x weeks CO effort and 15 weeks CSO effort. - Total is 536 hours according to USU reports. Does this include CSO effort?. Alastair spent 187 hours in total.

-- AlisonDownie - 18 Apr 2013

Edit | Attach | Print version | History: r16 < r15 < r14 < r13 < r12 | Backlinks | Raw View | Raw edit | More topic actions...
Topic revision: r13 - 08 Aug 2013 - 15:42:05 - 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