Review of user documentation

This document is an attempt to synthesize the various comments made to me in response to an earlier discussion paper on the state of our computing 'user documentation'. There is little or nothing here that will be news to anybody; all I am trying to do is formally to write down what the current situation is, what the problems are, and make outline suggestions for addressing them.


1. Current situation

  1. We currently have user documentation spread somewhat randomly over a variety of alternative containers (e.g. the Informatics website, the DICE website, the Wiki, etc.). This situation has arisen historically, and continues now since there are no clear guidelines detailing exactly where any new piece of documentation should be placed, or in what form it should be written. Currently, the amount of documentation on the Wiki is growing largely because use of the Wiki provides an easy option for the production of new material, rather than, necessarily, an appropriate home for it.

  2. Within any existing documentation 'container' there are links to related material in any or all of the other containers. This is disorganised, makes navigation difficult, and gives a bad experience to anybody attempting to read about any subject from the top down.

    Random example: the page

  3. Our documentation containers are a confusing mix of information, advocacy and advertising: internal documentation is in some places mixed in with outward-facing documentation. It isn't clear what we intend each of the containers to do: simply to provide information? to promote and advertise what we do? ... ?

    The confusion arises because we don't have a clear idea of our target audiences, and of what the material is intended to achieve - but those two things are necessary conditions for the success of any piece of writing.

  4. The DICE website is a mess. It contains valuable technical and historical material, but it isn't obvious (unless you happen already to know) exactly what information it does contain, and the homepage at offers no particular justification for its existence: anybody not already in-the-know who happens upon this website will wonder what it's for. The split between the two sites and is simply confusing for most people.

  5. We don't have any organised way for users to contribute to our documentation efforts. Existing efforts to implement such a thing via various Wikis seem ineffectual and moribund.

    Random examples: the 'Condor' section of the main user support systems page has a link to; the 'Self-managed help' section of the same systems page is a link to

2. Propositions

2.1 Target audience

  1. We have four distinct audiences for our computing user documentation:

    • Our local users. These users need detailed explanations of the services we offer, detailed how-to material, answers to FAQs, etc.
    • Ourselves (i.e. C(S)O's). We need a repository for all the technical documentation we generate.
    • The outside world:
      • External users of services (I am only aware of iFriend users, but there may be others). These users need detailed explanations of the relevant services, detailed how-to material, answers to FAQs, etc.
      • The rest of the world. These are people who may be wanting to find out what we do, or to whom we want to advertise and promote ourselves.

    We need to produce sets of structured documentation appropriate to each of these four audiences. The content in all cases isn't necessarily mutually exclusive but, in terms of its design, each documentation set should be considered a separate self-contained and self-consistent entity.

2.2 Form of the documentation

  1. All of our documentation must be web-based.

  2. We should not mandate how and when any such documentation is read: it should be as platform- and media-independent as possible. Specifically, all material should display satisfactorily on all web browsers, and it should be capable of being printed to paper satisfactorily.

    (Random examples of pages which currently can't be printed easily: the monolithic FAQ at; the LCFG buildtools documentation at

2.3 Coherency of the documentation

  1. The detailed overall structure of our documentation, and its coherency, are human problems which can only be addressed by a human editor.

  2. Our documentation should be in general be organised by service, and not by internal organisational Unit. No user of the documentation really cares who looks after a particular service; in any case, our Unit structure may change.

  3. We need permanently to disentangle organisational documentation (e.g. minutes of Operational and Development meetings; information specific to particular organisational Units; transient operational material; etc.) from our computing 'user documentation' and, from now on, locate such material elsewhere. The Wiki should provide a suitable home for most such organisational documents; if not, then they should be moved to a separate area of the website.

2.4 Technology

  1. In order to benefit from previous work and to safeguard future work, we need both to be able to transfer existing HTML documentation into any new website structure, and to extract HTML documentation from any new structure, ideally programatically in both cases. This almost certainly precludes the use of anything like the University's Polopoly service.

  2. Our documentation should be an integral part of the main Informatics website(s), and we should use whatever technology arises from the Future direction for the main Informatics web service project to author it. In practice this probably means reimplementing our existing documentation using Zope/Plone since this is expected to replace the existing CVS service which underpins the current user support site, as well as the DICE site.

  3. We should rely on external search engines for the indexing of our material, rather than try to provide our own search facilities. By now, most people expect to use Google etc. to do such searching, so we should concentrate our efforts on making that work as well as possible.

3. Proposals

  1. We should appoint an editor whose job it is to oversee the overall structure of our documentation, to commission its production, and to oversee its maintenance. Note that the editor isn't (and can't be) expected to do the actual authoring work, but must have the power to ask others to produce work on reasonable time-scales. In other words, the production and maintenance of documentation has officially to be given adequate priority.

  2. To keep the effort manageable, we should first restructure and rewrite the documentation targeted at our local users. That should give an adequate real test of the suitability of Zope/Plone, as well clarifying the effort involved in migrating existing material from the DICE website.

  3. A subsequent effort should focus on our own internal technical documentation, and deal with the reorganisation of that by service. In the course of that effort, all useful internal technical documentation which currently lives on the DICE website should be migrated.

  4. We need to debate the future of the DICE website and decide firmly what its future is.

    Several people have strong feelings about this, and there is certainly relevant content still on the website, as well as important historical content. At the least, all currently relevant content should be migrated to the new documentation structures, and the CVS history of the rest should be retained. The question then remains: what of the website itself?

    I do not myself think that an unwillingness to break any external links which may be pointing to the DICE website is a good enough argument to retain it (we can rely on external indexes to catch up with any important material on the new sites; we can provide a 404 page to help anybody using old links), but other people strongly take the opposite view. If we do decide to retain the DICE website, then we need to clarify what its purpose is, what information it should contain, how it should be implemented, and who should be responsible for it: it certainly cannot be left in the state it's currently in.

    All of this relates to the following question.

  5. We need to debate questions of advocacy, self-advertising and 'branding' in the context of our documentation efforts (even though these are really very distinct questions), and decide what it is that we are trying to achieve.

    Do we want to, and are we trying to, 'promote the DICE brand?' If so, exactly what is it that we are trying to promote? How should we go about it?

    The LCFG project has its documentation on the distinct site, with the intention that all non-Informatics-specific LCFG documentation be hosted there. Is this something we should do with other efforts here, e.g. Prometheus?

4. Other related questions

  1. How can we find out what documentation our users want?

  2. How can we allow users to contribute to our documentation? How do we edit any such contributions? How do we make sure that there is a clear distinction between 'official' and 'contributed' documentation?

  3. The suggestion's been made that users find it hard to identify what services we offer and, in particular, find it hard it identify which service they should be using to satisfy a particular goal. This failing may not simply be one of documentation, but how can we try to address it?

  4. Project reports need an organised home, and ideally it should not be possible to edit any such reports once they have been submitted.

    The best solution would be to extend the devproj system to store any 'official' documentation pertaining to any project in the same database as underpins the rest of the system. An easier fix is simply to create a formal 'projects' section of the new technical documentation area which contains a home page for every project, and which is the mandated home for all documentation pertaining to that project. The 'Url' field in each devproj entry can then simply point in a standard way to this location. This suggestion merely formalises arrangements which have in the past been made for various projects.

-- IanDurkacz - 20 Nov 2009

Topic revision: r4 - 01 Dec 2009 - 11:57:27 - 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