DICE Internal Technical Documentation - Where Now?

These are the salient points which I took away from the meeting on internal technical documentation held on the 30th of September 2015. Please add any comments you may have to the end of the document in the hope that some decisions may be reached and a record created as to how those decisions were reached.

  1. Currently our technical documentation is something of a mess, spread over several technologies. Unless you know exactly where to go, it is very hard to find information on a specific subject (you either need to know on which technology the information is likely to be stored on or search each of them separately). Even if you do find the right location, the search results may contain so many superfluous results to render the entire exercise futile.

  2. Ideally we would create a new central location for all this documentation and would migrate all content to it. Experience with computing.help showed that this would be a massive task and probably never completed. Certainly we don't have the effort available to attempt such a move currently. In any case, there were strong arguments made that different technologies are better suited to certain types of documentation so we probably wouldn't want to mandate one technology for documentation anyway.

  3. The next best solution was generally agreed to be to set up a centralised index of pointers to existing documentation. Drupal was seen as the most likely technology to host this index. Though this website (provisionally called dice.inf.ed.ac.uk) would be an obvious place for any future documentation to go, this would not be mandatory.

  4. Each entry in the index would have a number of tags associated with it. Tags would be freeform but someone would be nominated as a 'tag editor' to try and ensure that we don't end up with a plethora of different tags all meaning the same thing. The index host would provide facilities for searching by tag.

  5. One of the major questions to be answered is how this index would be generated and maintained. There are two schools of thought. One maintains that entries to the index should be added and updated manually using a UI or command line tool as yet unwritten. The other considers that the index information, including the tags should be embedded into the actual document (in a format as yet to be determined) and gathered automatically. For documentation where tags cannot be embedded easily (for example PDFs), a wiki or HTML page would be created which included the tags and provided a pointer to the actual documentation.

  6. Either way, the majority of the effort spent during the forthcoming documentation week would be on tagging the existing documents which should appear in the index. This requires, of course, that the indexing/tagging mechanism be in place for documentation week.

  7. There was agreement that the indexing/tagging mechanism needs to be as lightweight and easy to use as possible.

  8. To get a feel for how useful this exercise is likely to be, it was suggested that Units might like to spend an afternoon tagging some their documentation (in a very lightweight way such as sticking them on a wiki page or in a text file) to see what issues arise.

Please add comments and questions below. The next step will probably have to be decided by CEG when they next meet on the 12th of October so have your say before then.

Comments and questions

  1. FWIW I disagree with the conclusion of point 2. I think a new central location is the right idea, and I don't think the effort in migration would be too great.
  2. What (ignoring the 'deep' content on that site; some of which is the very documentation we're talking about) are we doing about the site www.dice.inf.ed.ac.uk?
  3. In point 3, why is 'dice.inf.ed.ac.uk' chosen? Why not use www.dice.inf.ed.ac.uk?
  4. Where should brand new documentation (i.e. documentation for which there is no existing 'established home', either on www.dice.inf.ed.ac.uk or the wiki) go? Are we having a new central location for such stuff?
  5. I don't see how we can start doing what's described in point 8 without more explicit guidance - or at least some examples - showing what's wanted.
-- idurkacz - 02 Oct 2015

CEG discussion

CEG discussed the comments and questions above at its meeting on Monday 19th October. Salient points:

  • Because of the nature of some of the documentation (e.g. lcfg.org) it's inevitable that we won't be able to have One True Location for all of our technical docs. We'll just have to accept this, and adapt our tools and ways of working to suit.
  • Tagging pages with metadata was supported as a Good Thing, whether or not the tags are then used directly or through some kind of search tool. We do need at least a Tag Tsar, even if not a full-scale editor.
  • There was some debate as to the best way to implement searching. Simply using an outside engine (e.g. google) to index everything isn't possible due to the presence of restricted pages. It seems likely, though, that we're not the only people wanting to do what we're trying to do, and that there are likely to be solutions out there.
  • There doesn't seem to be any obvious alternative to drupal for the top-level dice.inf site. Craig will prototype something.
  • We do need to revamp at least our landing page, to be dice.inf. Other pages should be linked clearly from this, either directly or through sub-index pages on the new site. There's the suggestion to redirect the www.dice index page to this new page, though keeping all of the remaining pages on the site accessible as now. The site search page, however it's implemented, would be linked from this index page rather than being the landing page directly itself.
  • The default location for new documentation should be the new site itself, though other factors such as whether there are already similar or related pages will also weigh.
  • We don't really know enough about the options at the moment to hold Documentation Week in November. It'll be rescheduled.

-- CraigStrachan - 30 Sep 2015

Topic revision: r5 - 20 Oct 2015 - 13:44:35 - GeorgeRoss
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