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
.