As I mentioned in my previous post (“A New URL for My Old Blog” … if you haven’t checked it out yet…go do it…I’ll wait…), I have started blogging again using emacs and org2blog after a long hiatus (the last actual post that wasn’t just a re-post of a link was two years ago). I mainly do this out of being a complete nerd rather than any sort practicality. I used Emacs throughout my Computer Science university career as it was readily available on lab computers and it was part of my Linux distribution by default. It also helped that I had (and still have…) a passionate hatred of the terrible user interface of Vi. Cue the angry howls of Vi users

Where was I? Oh, the point of this post is to talk about the importance of documentation. Seeing as it’s been very nearly two years since I created a WordPress post on emacs using org2blog, I’ve forgotten almost all my clever org-mode formatting tricks I would use for a blog post. Thankfully, I created a number of useful posts on my last iteration of this blog outlining clever things like “Quick Post About Uploading Images Via Org-mode and Org2Blog” and my “TILiE (Today I’m Learning in Emacs)” posts (which I still think is a neat blogging format idea that I should return to…). Without the documentation I wrote as part of my blog posts and other great documentation resources, I would have been forced to start the learning process again from scratch.

Writing documentation is a giant pain in the ass; let’s be honest. I do it as part of my day job and it sometimes drives me crazy (and I’m the documentation evangelist of the team too…). There is something distinctly unsexy about writing documentation. It’s like we’re experience junkies, always moving on to the next new thing, too busy to record what we’ve learned. Since the best documentation is written from the perspective of educating a reasonably intelligent (possibly a stretch in some cases…) but untrained audience, you really need to plod in your methodology. You have to outline every little step and make sure you have good annotated screen captures to go along with everything. Even someone with the strongest willpower eventually starts pulling out their hair. Writing documentation is maddening!

But…

Without it, we’d be constantly figuring out how the hell to do that clever, time-saving shortcut, going slowly crazy because we know that it exists. Yes, yes, we could Google it but that only proves my point that documenting what you’ve learned is extremely important. By googling it, you’re just putting off doing it yourself and hoping that someone else was kind enough to document the steps to whatever it is you’re trying to do.

I also find that the process of documenting a task or skill makes me learn it much more thoroughly then I would have otherwise.

Anyway, I don’t want to belabour the point but I really feel documenting your processes is important. It’s saved my bacon more than once and it’s helping me now. 🙂