Sysadmin Documentation
If there’s one sure thing in the life of a sysadmin (besides late night alerts and early burnout) it is that sooner or later and probably sooner, you will need to document what you do, not just for your own use but also for those you work with or who will follow you when you have moved on to greater things (or got run over by a bus). How should the diligent sysadmin set about this task?
Documentation is not fun – there I’ve said it.. it is tedious, boring and time consuming.. but it can save your bacon when the SHTF. How you go about the task, what tools or processes you use can depend on a number of factors such as personal preference, amount of documentation you need to produce, company policy etc.
The simplest form of documentation is the humble text file – write down scraps of info as you go along and you’re done, right? Well, such a method might work on a small scale but as the amount of documentation grows a simple text file soon becomes a mess which is hard to maintain (if it ever gets any updates at all) and hard to find what you need even if using such super advanced tools as the ‘find’ link in your text editors menu.
Some sysadmins, particularly those with real technical writing training or experience might opt for producing rich documentation using a proper word processor, with screenshots and tables etc etc. This is certainly good for documenting software, a product or service, used by others who would expect a proper user manual but it is still far from ideal for the sysadmin who has to deal with an ever changing array of items and issues and documentation that may need to be used and updated by many people within the company and perhaps even around the world.
A popular option these days is to use a wiki – either installed on a public web server or a private server on your office intranet, whichever works for you. A wiki allows for easy creation of articles to document a specific process or item and it can be collaboratively created and updated, they are also searchable and have a rich internal linking structure as well as being able to easily link externally to any relevant information. A wiki will quickly grow into an essential resource which you will find increasingly useful in your day to day work, as long as it is not neglected.
Another option is to use one of the various documentation tools available, many of which are tailored to specific use cases so you will have to find one that suits your requirements. If you are using a ticket tracking system such as RT from Best Practical, you could use their RTFM system which as of RTv4 is fully integrated with RT so no need to install another app.
If you are really feeling particularly geeky or just have way too much time on your hands, you could even develop your own documentation system – a few perl scripts with a mysql database and a fulltext index and you could have a cool custom documentation tool to amaze and impress and make your workday more efficient – as long as you don’t spend all your working time developing and fixing that! Of course if you do opt to develop your own – make sure to document it.. 😉
If you’re in need of documentation for your systems or your startup, and you can’t face doing it yourself, you should check out our technical writing service!
