In 2008 I gave a talk at the UK UNIX User's Group 2008 conference and workshop entitled Organising sysadmin documentation. Here's the abstract, and slides odp (697K) and pdf (735K).

Most professional teams will have some form of team documentation used as a reference by existing team members but also as a means of getting new staff up-to-speed. System administrators are no exception, but have their own set of additional requirements: lots of diverse, complex systems mean lots of procedures to recall. It's also no good having procedures for repairing a database server stored in a database table.

I recently undertook a project to migrate Newcastle University UNIX team's internal documentation from a simple filesystem-based scheme to a web-based wiki system using "mediawiki", the software that powers Wikipedia. Once I had achieved this, it became apparent procedures and tools were necessary to help manage the continued review and updating of the documentation. I also became aware of several issues with the approach that impacted us specifically as systems administrators.

Since then I have discovered ikiwiki: a "wiki compiler" written by a notable Free Software hacker which promises to be a great deal more friendly to systems administrators. ikiwiki supports online and offline operation; back-ending to a real version control system; plugins to tweak nearly all facets of the software's behaviour.

My talk will explore the issues uncovered as part of our first migration, including managing the continued review of material; identifying holes in the documentation; identifying different "classes" of staff and what motivates them to participate in team documentation efforts. I will then discuss Mediawiki and Ikiwiki in detail, looking at their feature sets and drawbacks, in particular relating to sysadmin-specific requirements.