Documentation = Learning
December 15, 2012
I came across this great article by John Sansom, and it got me thinking.
I personally think about documentation as a way of cementing what I’ve just installed, configured or developed. It helps me remember. So I document everything.
“If you can’t explain it simply, you don’t understand it well enough” – Albert Einstein.
I think of documentation in the same way.
We have a team wiki where all our documentation is saved and I pride myself in directing team members to docs that I’ve written. I use the level of follow up questions asked as an indicator on the quality of the material.
Quite simply, if there are too many questions, then it’s not good enough. It’s an easy way of learning and making sure you understand it as well as you think you do.
It’s quite similar to mentoring junior members of the team. Never shy away from the opportunity as it’s such a great learning resource. New members or juniors throw all sorts of questions at you and it really helps you revisit your theory, and areas that you’ve either forgotten about or simply not visited in a while.
Thanks for reading.
Added 19/02/2013 – Another great blog post by Argenis Fernandez related to documentation, focusing on using a Wiki. My comments below:
A wiki is a great tool to store documentation. We currently use confluence which is easy to use and adopted well within the team – even for collueages who are not fond of documentation they quickly saw how easy it was to update and then how good the search utility is (searches within uploaded content too).
One downside (to add to Brent’s comment) is when we perform our yearly off-site DR test, this wiki server has to be built and recovered first (using printed off DR build documents), before we can recover any of our other servers.
In addition, we’ve implemented a script (vbs/wmi) that runs weekly, which grabs all prod server information and writes to idividual server text files, which are then imported into a infrastructure database. At a moments notice we can email a servername_date_config.txt file to whoever needs it – which is a lot fast than querying an infrastructure database and formatting the output for someone to read.
Scripting really is the only way to ensure that your infrastructure database is up-to-date and correct. Humans are really good at forgetting to update. Great article!