Write Your Documentation as a Script

Which would you rather have: a document telling you how to start an application in 10 easy steps, or a script (shell, Perl, Makefile, etc.) that does it for you?

I’d pick the script:

1. The script is self-documenting. You can look at it and see what it will do. If you need to troubleshoot something you can just run the commands yourself. If you need to change the documentation you just change the script.
2. The script can help ensure that the environment is correct for the application. Do you need to set environment variables, like JAVA_HOME, ORACLE_HOME, etc.? Just do it at the top of the script.
3. You can call the script at boot, and have the application start automatically. Patching and rebooting a whole bunch of servers? Having the applications come up on their own is a godsend. Plus, if you put it in rc.local and not in the init.d system you can easily comment it out if you don’t want the application to start at boot. (Update: there is some discussion about this in the comments)
4. Anybody can run the script without knowing anything about the application. You’re on vacation? Your application died? No problem! Another admin stepped in and restarted the application without knowing anything about it, thanks to your script. This is especially easy for someone else if you always name your scripts the same way, like START.sh and STOP.sh, or if you call the startup scripts from rc.local. They can just look there to see how it is done (or worst case, reboot the server). (Update: there is some discussion about this in the comments)
5. You can call the scripts from cron or a monitoring system. Sometimes it is nice to automatically restart an application at a certain time, or when a problem is detected. If you already have a startup script then you don’t have to write one. 🙂
6. The script avoids typos caused by poor cut & paste, line wrapping, inability to comprehend what the documentation says, etc. It also avoids dependency loops, like where the documentation is in a wiki which depends on a database, and the instructions for starting the database are in the wiki…
7. Written documentation is the last thing to be tended to in most organizations, and even if it is up to date it may not be well tested (by someone other than the original author). However, if your document is the script you use to start the application it won’t be as easy to get away with not having it updated. And you’ll know it works.

Downsides? Yeah, there are a couple. First, to read this form of documentation you need to understand the scripting language it is written in. You should pick a language that everybody on your team knows, and comment things well. A little peer review at a team meeting can help, too, by explaining what it is you’ve automated/scripted and how it works under the hood.

Second, management types often don’t understand that scripts of this nature can serve as your documentation. So they give you a hard time for appearing to not have any documentation at all. When faced with this problem I’ve dealt with it by mentioning that in addition to English, most of my teammates understand various programming languages, too. We’ve just chosen to write some of our documentation in that form, those languages. Then we get the benefit of being able to run our documentation, which saves us a lot of time and hassle. Which, in turn, makes us more productive.

🙂