A while ago, I read a post from Tom McFarlin about keeping a change log. I had actually just started a massive project and was scrambling to remember what I did the previous month and why. Also, we had promised to deliver technical documentation and user manuals. I figured that I would get through the project (which was due at the end of November) and spend a day or two developing the documentation at that point.
Bad idea. Here’s why…
It’s Easy to Get Lost
In his article, Tom gives two primary reasons for keeping a changelog (and I would include any documentation):
- Re-learning your work
- Identifying what went wrong
Even though I was up to my ears on this project and it was all I had thought about for a month, I still forgot and had to remember and re-learn what I had previously done. Data wasn’t where I had put it (actually it was, but I had changed the associated keys), I couldn’t remember certain steps for updating things, code snippets weren’t readily accessible, etc.
In short, I needed a quick review on everything I’d done. Upon reading this article, I immediately started a changelog and technical documentation in markdown documents. In the future, I think I will create these at the beginning of the project.
Writing Everything Out Is Very Clarifying
When you have to verbally communicate what you’re doing (and even why you’re doing it), thoughts, procedures and practices need to reach a level of clarity that the users (and my future self) can comprehend and act on.
Code snippets, plugin file contents, and rationale are all important for me to know and recall. I might have done something a certain way for the first time in my life, never to repeat. How would I remember how I did things and why without solid documentation?
It’s the Responsible Thing to Do
What if I got hit by a bus tomorrow, or even worse, fired from this project?! (Ok, getting hit by a bus would be worse!)
Basically, if I’m not around, or have moved on professionally, who’s going to maintain the site? How will they know what to do? Documentation allows someone to come in and get up to speed quickly.
Also, I will say, if I was in the zone, I could work for hours without getting up. However, if I didn’t immediately document what I was doing, my what and why of that stretch of decisions might have been lost. Immediately documenting what I did and why was very important.
Without disciplined documentation, you’re setting your client and yourself up for a big mess.
It’s a Nice Break from Coding
While this isn’t always the case, documentation was a nice break from coding and building. I could relax a little bit and think, “I’ve just got to get the words on paper.”
It also seemed like a good reflection exercise. Several people end their day with reflections of what they did and gratitude. I felt like documentation was very similar to these exercises: a nice way to wind down and shelve the coding and building activities for the day.
I don’t think I’ll ever do another project again without starting at least some form of documentation.
###
Peace,
Nate