Document as You Go

Intro. the documentation challenge

One habit I strongly recommend to tech practitioners is to document as you go. The usual habit is to try and document everything after you’ve done a new task or completed a troubleshooting item. This rarely works.

Usually you’re tired. You’ve forgotten steps or the order things have happened. This is especially true if you’re troubleshooting an issue. You don’t remember exactly what you changed or when, you just know it’s fixed now. So if you want to go and document the issue, you really can’t. If you encounter the issue again later or you have to repeat it, steps are missing or out of order.

If you get started troubleshooting and you try various items and then have to open a case with a vendor or involve another resource, support needs you to be able to explain what happened and when. “Did I alter that /etc/foo.conf before or after I added the package”

So the best thing to do is capture it all as you’re doing it. At the same time, you don’t want the process of documenting to slow you down. You need it to feel seamless.

Techniques for documenting on the fly using CLI tools

One of the many reasons I prefer to use the CLI is it makes documenting on the fly a nearly frictionless task. In the linux/unix world I’ve long used screen and now tmux because they aid greatly. It’s a simple keystroke to start logging everything to a file. Then prior to executing commands, I can simple run the date command to produce a timestamp.

Using the date command in this way as part of the buffer capture allows me to time how long certain items might take. And if I’m dealing with troubleshooting, there’s probably going to be a management request to build a timeline of events. In this way, I don’t have to “guesstimate” several days later to produce that timeline.

Since I’ve logged everything in a file, Generating procedure documentation also becomes a simple process. I strongly prefer used text-based markup because I find it far simpler than using, say, Word. I can take a tmux log and just wrap sections in “preformatted” markdown with a little bit of explanation and my technical documentation is pretty much done.

Techniques using the GUI

Operating in a GUI and documenting on the fly generally requires some additional effort. I’ll pop open a text editor to log actions. Since I’m usually on a Linux desktop, I’ll use shutter to capture screenshots along the way.

The issue here is that it’s a bit more intrusive then just capturing a log as you go. I have used tools to capture a desktop recording as well but I don’t find this to be a good technique for most documentation. The main thing is to be rigorous about capturing notes in a text editor and loggin timestamps along the way.

Writing tools

As I mentioned before, I strongly prefer text-based tools and simplified markup to using a word processor. It’s easy enough to transform markup into Word, PDF, or HTML as needed. I’ve gone back and forth between using markdown and Emacs org-mode . Both work well but I am favoring taking notes and documentation in org-mode lately. It’s easy enough to convert org markup to markdown and vice-versa with pandoc .

I’ve also played with geeknote for using markdown to put my notes and documentation into Evernote. But for the most part I’m using org-mode and putting docs and notes onto Dropbox and/or a personal git repo.

What about Windows?

I’m a *nix guy but of course I work in Windows environments as well. I’m finding myself using PowerShell quite a bit in part because I can work with it in the same way I do with BASH, Perl, Python, etc. I’m still looking at various ways of capturing the buffer log with PowerShell as well as using Set-PSDebug -Trace 1 to provide similar functionality to sh -x when executing scripts. But I’m newer to that world so suggestions are welcome. It is tempting to just use Cygwin and proxywinconsole to run inside of screen or tmux.

 Share!

 
comments powered by Disqus