Review of user documentation

The 'Review of user documentation' project (devproj #36) has the aim of 'review[ing] the Informatics documentation for users and computing staff - which is currently spread across, the DICE pages, and the Wiki -, with the aim of developing a coherent, searchable structure.' The inherent implication is that there is general agreement that the current set of documentation is neither particularly coherent nor easy to search.

This initial note seeks merely to document the current situation in order to solicit input from the CO community. We need collectively to establish and/or decide upon:

  • The intended audience for our set(s) of documentation.
  • The scope of our set(s) of documentation.
  • An organizational framework for our documentation, and some kind of search technology or tool which encompasses all of our documentation.
  • A maintenance mechanism - or regime - which ensures that all our documentation is kept up-to-date, and/or routinely culled as necessary.

Note that although we are restricting this review to 'computing' documentation produced by the CO community for either its own use or for use by the wider user base, the underlying problems (and any possible solutions) may also apply to some/most/all of the on-line documentation produced by the School.


1. Current computing documentation

We (i.e. the C(S)O community) currently produce two main types of computing documentation: 'user documentation' directed at the entire user base, and internal 'technical' documentation directed at ourselves. All of this is currently spread across three main websites:, the DICE pages (, and the DICE Wiki (

User Documentation:

  1. Computer Systems section at

    The User Support Unit maintains these pages, and the current structure seems both reasonable and coherent provided that the information presented is kept up-to-date and complete. At least some of the current documentation is out-of-date. (E.g. the section about 'Authportal' should be removed. How relevant is the 'Using DICE Laptops' information? etc.)

Technical Documentation:

  1. DICE pages:

    Collectively, these pages appear to be the main collection of technical documentation. Some are being actively maintained, others not; the entire collection contains much that is historic. The technical documentation content appears to be as follows:

    1. Inf Unit documentation:
    2. RAT Unit documentation:
    3. Services Unit documentation:
    4. User Support Unit documentation:
    5. Old 'team' documentation, some of which is still relevant:

  2. Wiki: The School TWiki site hosts various 'Webs', but the 'DICE' Wiki contains the material relevant to this discussion and is at This is a growing but disorganised collection of technical documentation - the content appears to be as follows:

    1. Inf Unit documentation:
    2. MP Unit documentation:
    3. RAT Unit documentation:
    4. Services Unit documentation:
    5. User Support Unit documentation:
    6. Various:

Documentation which is also relevant is also being created on the not-a-service blogsite; there may also be some useful documentation on the personal homepages of individual CO's at

2. Current indexing and search

We offer a 'search' page on our main website - at - which gives three distinct search options:

  1. Search our public pages (i.e. those of our pages which are accessible to external spiders) via Google, by the assertion of the option.

    Note that Google can obviously only index those of our pages which are publicly available; the ones it can't index are those which are either limited to access by Edinburgh netblocks, or which are Cosign-protected.

  2. Search the entire web with something called 'Site Flavoured Google' which has been configured (it is not clear to me, how) in an attempt to favour results 'of interest' to a member of this School. The results returned are not restricted to our websites.

  3. Search our website(s) using an internal index generated nightly by the harvest-ng spider and the zebra indexing engine (see

    The internal index takes about three hours to generate each night, and covers those websites hosted by us which are listed in the file beezer:/disk/drookit1/infweb/search/sites.conf; in particular this means that the sites (and, therefore, our user documentation section) and (and, therefore, that part of our technical documentation which is located in the DICE pages) are indexed.

    This index can cover both public pages, and private pages which are limited to access by Edinburgh netblocks. It can't currently cover pages which are Cosign-protected, nor those addressed via https, though the latter restriction could probably be lifted. In particular, our Wiki pages are not currently covered by this index.

The summary is that user documentation is probably (?) served well enough by the current search mechanisms, but technical documentation is not.

3. Discussion / Requirements / Propositions


  1. Truism: all of our documentation must be web-based. It must also be suitable to be printed to paper whenever necessary.

  2. Truism (?): there can be no techno-fix to the problem of coherency: that is a human problem. Whatever framework or structure we choose, we need human input to decide what documentation we want and how it should be organised. Likewise, routine maintenance/updating/culling of documentation requires human input.

  3. It seems reasonable to continue to have two distinct collections of documentation, as at present: one for end users, one for C(S)O's.

  4. Any text-based documentation we produce must be in some plain-ASCII marked-up format - presumably, in fact, HTML. Whatever format is used should be easily convertible to other formats, and we need to ensure that any content management system we use (including any kind of wiki) allows us to both enter and extract material in the raw marked-up format in order to prevent us becoming locked-in to any system.

  5. All user documentation should be publicly-available, without restriction. There may (?) be a need to be apply access restrictions on some of our technical documentation.

  6. The 'future direction for the main Informatics web service' project (https://devproj/project/show/93) has obvious implications for this review, and the 'improve search technology' project (https://devproj/project/show/45) is also obviously relevant. It would be a good result if whatever content management system we eventually settle on provides a good home for our documentation, and it seems reasonable to expect that: there is nothing in our requirements that will not also be needed by other users of the web service.

User Documentation

  1. The current documentation directed at end users seems to be coherent enough; the form it takes seems reasonable; it also seems to be indexed and searchable sufficiently well by either the current local search mechanism or the Google site-directed search. It needs to be routinely reviewed and updated in order to keep it up-to-date.

Technical Documentation

  1. Technical documentation directed at ourselves is in a very disorganised state and is randomly spread over several websites. In practice, even where the documentation is complete on any subject, things are hard to find, and - critically - it isn't clear where any newly-produced documentation should be placed. In addition, not all of our technical documentation is either indexed or searchable by the current mechanisms.

    This situation seems to have developed over time: our internal organisation changed ('groups' and 'teams' changed into 'units') in a way that wasn't reflected by the structure of the documentation tree; the Wiki provided an easy option for new documentation; no explicit guidance for the production of new documentation was issued.

    Dealing with our technical documentation is the major problem. We need to decide on a framework which is mandated as the single container for all of our technical documentation. It needs to be something to which all existing material can be migrated as easily as possible.

  2. Technical documentation should be organised by theme, and not by organisational unit. Regardless of who is responsible for authoring any documentation, we all need to be able easily to find it, and read it.

  3. Some technical documentation is currently produced programmatically from e.g. source code. We need to incorporate such documentation within any framework.

  4. We need to decide which - if any - of our documentation should not be publicly-available.

  5. The 'DICE' website is an historical hangover which now has no relevance and there is no reason to persist with it. It contains a confusing amount of documentation, a great deal of which is out-of-date.

4. Summary and proposals

How to deal with our technical documentation - specifically, what framework we should use for it - is our major problem, and I am calling for suggestions from all C(S)O's on that subject.

Local search technology should also be reinvestigated (as per https://devproj/project/show/45) to see if we can improve what we use at present.

Meanwhile, I suggest (repeat: suggest, only) the following short term measures to improve the current situation:


  1. The 'Site Flavoured Google' search option should be removed from our search page - it adds nothing that users can't do themselves. We should continue to present both the site-directed Google search and the local search options.

  2. Our 'local search' should be reconfigured so that it also indexes the site

User Documentation

  1. This needs only to be routinely reviewed and updated as happens at present. Out-of-date items (e.g. the ones mentioned in section 1) should be dealt with, and any new content generated as required.

Technical Documentation

  1. On some short timescale, we should close down the site and delete all of its underlying filestore. Before that is done we need to:

    • identify any useful technical documentation currently contained within;
    • migrate all such documentation to a new website (or similar) which should be organised loosely by theme.

    I do not intend to try to mandate here what the exact logical organisation of the 'docs' website should be, but the high-level divisions should be obvious enough: LCFG, network, printing, etc. Nor do I intend to specify (here, anyway) how the 'docs' website should actually be implemented: the three obvious initial suggestions are a site using the existing CVS mechanisms, a wiki site, or a Zope/Plone site.

    The appropriate people to identify content to be saved from are those who now have responsibility for the subject matter of any of that content.

    Any other material on which is specific either to the organisation of a particular unit (e.g. current projects within that unit) or to the computing staff in general (e.g. the holidays page), and which still seems useful, should be migrated to the DICE Wiki.

    I see no reason for retaining any of the CVS history of the current site.

  2. The 'unit' sections of the existing DICE Wiki should not be used as a container for any technical documentation, they should be used for specific internal unit-based content only. Any technical documentation currently therein should be migrated to the 'docs' site.

    If that is either not easily possible, or is simply resisted, then, at the least, links to any technical material contained within any unit's Wiki page should be manually placed in the relevant section of the 'docs' website. The same applies to any technical information that is posted on either or The intention must be that the 'docs' website is both comprehensive and complete.

-- IanDurkacz - 22 Jun 2009

Topic revision: r10 - 26 Jun 2009 - 15:54:01 - 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