Skip to content

Instantly share code, notes, and snippets.

@hamishforbes
Created October 27, 2015 16:44
Show Gist options
  • Save hamishforbes/3fbc0d13cb968c4fcfdf to your computer and use it in GitHub Desktop.
Save hamishforbes/3fbc0d13cb968c4fcfdf to your computer and use it in GitHub Desktop.

Why should everyone write documentation?

If you're asking this question, you're probably french, or lazy, or new, or something else :).

It saves time for the rest of us

The initial time hit for writing a page of documentation is minimal compared to the time it saves others. A quick paragraph or two explaining why something is the way it is will allow someone else to quickly obtain information. If we need to know where a customer's systems are located or how to access the network statistics, then we don't want to spend a few hours trying to figure it out. That's time better spent doing something fun or productive instead of duplicating what the last poor schmuck went through.

There is (unfortunately) a ?school of thought that believes if you want to know something, you should duplicate the long solitary learning process. This is how information is lost. This is why there are fifty ways to do something that are shared among a dozen people with sole knowledge of them. This is the path of fail.

Another school of thought states that you can somehow document yourself out of a job. This may be true if your highly-paid job is to repeatedly press one button at a time of day only you know. It's not true in any job requiring thought. Managers who believe that with enough documentation you can replace intelligent employees with monkeys are doomed to fail and your job will end regardless of how painful your lack of documentation makes it for everyone left behind.

It saves time for you

There are many pages you'll create and use that are nothing more than forms for entry. Essentially mimicking databases, these table-loaded pages are designed to give you a quick place to update your docs. Updating a single field in a wiki table takes seconds and requires no custom coding of a cumbersome java GUI backend designed for accountants and office admin staff. It also allows you to look up information with a full-text wiki search so that you can quickly reply to questions.

Even in the case of a page you never use again, documentation saves you time. If someone asks you why we write documentation, you can direct them to this page and close the jabber window. Alternately, you can spend the next hour typing this all out to them. One takes less time than the other.

Hard disks remember things better than you, and they're backed up

If you grind through a lot of information in a day, you will eventually forget something. Many of the things you forget may be complicated and only dealt with (by you) several years ago. If you spent four hours figuring out something before, then you're going to spend another four hours figuring it out this time. All that lost time could be saved by fifteen minutes of typing up what you did.

Also, consider those times you go on holidays or are sick in bed. The last thing you or your team want to do is disturb you during your official "off" time. Give your team the opportunity and impetus to consult the clear, concise and correct documentation that you've prepared. Everyone wins, and I mean everyone.

Putting your name down = responsibility

When you hide what you've done, there's typically no name to associate with it unless someone else immediately notices. As time goes on, the employee who rode the failboat may have left and dropped everyone in a mess. If he/she had documented what was done, there would be two effects:

Everyone would have had a chance to notice and correct the documentation before it was required, If he/she did something really dodgy, then having to document it may force a bit more thought. If you wonder why your fellow employees might get anal about documenting things, the above reasons are why. No one wants to get screwed over.

Why should sysadmins write really good documentation?

J'aime mon fromage et vin avec un côté de stupide

Aside from all the reasons above, here are some specific reasons why you should be writing extra documentation.

You're the last line of defense

If something gets really bad, it will eventually come to you. That's the state you get it in - completely boned. It's something that's been escalated to you and now you're stuck with it and you can't decide that it's just too hard. Other people have that luxury. You don't.

Duplication of work hits sysadmins especially hard. Most of the work done involves many hours (or days) of thought followed by a relatively short amount of typing. Documentation reduces, if not completely eliminates, the large amount of non-typing work. The previously hidden, insurmountable problem becomes an issue of cutting and pasting a few shell commands. You change a line in the config, restart the service, and now suddenly you're going home at 17:00 instead of 01:30.

You're only one person

If you're the only one who knows how to do something, you'll get asked how. As covered above, linking someone to the appropriate wiki saves you huge amounts of time. In the case of sysadmins, however, it means more: you don't have to do it. You don't need to be interrupted in the middle of a big project to fix something because someone else can using methods you already investigated. A task assigned to you by someone who happens to know that you fixed something before can be reassigned to someone who isn't currently as busy.

A quick experiment: add up the hours it takes to reverse-engineer all the solutions that only you know then subtract that from the number of hours in a day. That's how much time you have to work on non-maintenance projects. If the number is negative, then that's the amount of unpaid overtime you get to perform. Unlike sales-assigned overtime, this is completely justified. You're just making up for being lazy and/or hoarding information.

You're the only one awake at 03:00

Human eyes are not meant to open in the wee hours. This is especially true if you just got home from the pub. Documenting simple quick-fix procedures that reduce a problem's severity (or fix it altogether) means you don't have to read much and can get back to sleep. Documenting long, complex procedures can ensure that systems don't die in the middle of the night. That's more sleep time for you and less proxied customer yelling coming from management.

A more negative aspect to this is that you won't always be the one waking up at 03:00. If you're up all night fixing something due to a dirty hack someone else put in, that's justification for beating them senseless the following day. Doing something volatile/tricky and not documenting it is double fail and equates to doing it on purpose. Sysadmins can't afford that atmosphere because...

We're all in this together

Sales can compete for commission. Project Managers can compete for bonuses. Sysadmins can't compete for anything. You simply cannot perform the job in an environment where everyone is out to build their own empire.

There is a rather large amount of trust that gets handed over when your ssh key is added to the root account. Sysadmins depend on each other for information, obscure skill sets (that hopefully generate invaluable documentation) and keeping morale high with random cartoon references. Every page of time-saving documentation you write saves the guys around you days of misery. That time and misery saved can be directly converted into more documentation to save even more time and misery.

Those savings can then be converted into beer time, and let's face it, everyone loves beer time, no matter what you drink.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment