Document, document, document

Long ago, I used to work on DEC OpenVMS systems. VMS was an elegant, logically constructed operating system which made the messiness of Unix and Linux a shock when I encountered it. For example, I can still remember the commands to check the disks, system and memory on VMS. When you see what they are you realise it’s not a great feat of recall on my part:

Show disk, show sys, show mem

The nearest Linux equivalents would be something similar to this:

Df -lhk, ps -ef, free-m

We can see where the trophy goes for intuitiveness.

These VMS commands had various qualifiers such as /all /full etc which were consistent in their meaning unlike the switches in Linux and Unix. I can understand why the latter prevailed, but VMS was a joy to work with.

You could construct command files in DCL (Digital Command Language) as you would scripts on Linux and I came up with one which ran from a central server and queried the client servers’ disk space and memory then emailed the support desk if it was running low. It was fairly basic but there was a bit of network gubbings underpinning it as I recall and it did need something setting up on the queried server too. (It used new-fangled TCP/IP as opposed to Decnet)

I left that company and not too long after a friend and colleague rang saying they were adding a new node and he’d like to incorporate it into the monitoring utility so how did it work? I couldn’t remember and I hadn’t written any notes so the new node could not join the happily monitored family.

Nowadays, I document as much as I can, as too often I’ve been on the other side of the above experience. I read a lot about DevOps and Agile etc and I worry that in both credos’ emphasis on speed and efficiency documentaton is easily sidelined or done half-heartedly. I used to work with an architect who always had to fight for the extra time in a project to do the documentation and diagrams and can’t imagine this situation has improved.

In my opinion, documentation for a system should explain the data flows, dependencies (service accounts, spns, certificates). It should have a troubleshooting section highlighting where issues might occur, and perhaps those enountered in development. Even then, it will still probably date and not be maintained but it will give some poor sap the clue he or she needs to fix something further down the line when the fanfare of the big launch has faded.