• Pingback: Tweets that mention Your Lack of Documentation is Costing You More Than You Think | John Sansom - SQL Server DBA in the UK -- Topsy.com()

  • Pingback: @JohnSansom posts Your Lack of Documentation is Costing You More Than You Think | sqlmashup()

  • http://blogs.softartisans.com Claire

    Couldn’t agree. We actually delayed our last release for two weeks so we could make sure all the documentation was up-to-date. The docs part of both our internal and public-facing sites have heavy traffic, and it would be disastrous if we didn’t provide in-depth guides to every facet of every product–even if creating them is time consuming!

  • Pingback: 10 Things Every DBA Should Do | John Sansom - SQL Server DBA in the UK()

  • Pingback: Something for the Weekend – SQL Server Links 08/04/11 | John Sansom - SQL Server DBA in the UK()

  • Pingback: SQL Server Central()

  • Pingback: Something for the Weekend - SQL Server Links 08/04/11()

  • Hugo Mendes

    Great article John.

    documentation = learning.

    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, areas that you’ve either forgotten about or simply not visited in a while.

    • http://www.johnsansom.com John Sansom

      Thanks Hugo, I appreciate it!

      Having a Wiki is a great idea and tool, especially in larger organisations. I think your attitude concerning documentation is spot on and that it takes discipline to maintain such a quality level. Good form sir.

      Your positive outlook on junior team members is also commendable and there I was thinking they just like to bother me ;-) Seriously though, as you quite rightly imply, teaching is as valuable a learning experience for both student and mentor.

      Thanks for your comments.

  • Pingback: Documentation = Learning « Hugo Mendes()

  • Pingback: The Great DBA Getaway()

  • Cody

    A huge challenge is getting people to write “proper” documentation. The thing is when people are forced to write something they don’t want to, they end up writing a dozen page Word document that is full of waffle, interspersed with assumptions about previous knowledge, and still addresses zero of what someone would actually need to know.

    What is this, exactly how does it work, how do you install it, where is the configuration stored and what changes did you make, what errors can it throw, what are some solutions to common problems?

    I regularly see a dozen pages without a single one of those questions answered :-/ Then I complain the documentation is garbage, and people become even more angry about being forced to write it and refuse to do more.

    “What don’t you understand?” they ask, ignoring the massive swathes of undefined text, and vague references to outside sources like, “It’s too complicated to explain how to compile and install this SQL CLR so look it up in BOL.” Would it have killed them to include their script? Oh right, they didn’t save the script, BECAUSE THEY DO EVERYTHING EVERY TIME BY HAND!

    Crap documentation from crap developers leads to crap products.

    • http://www.johnsansom.com John Sansom

      The phrase “Garbage In, Garbage Out” holds true to many walks of life sir.

      You touch on an excellent point there, the fact that an author must always write with their audience in mind. Sometimes the author is the audience but not always.

      There are of course many different types of documentation to consider, which in turn influences the nature of the content to be created. It can often be beneficial to define guidelines for how documentation should be created for your specific organisations’ needs otherwise it will be a free-for-all in terms of what results to expect.

      Some folks would argue that at least some documentation is better than none at all however, I suspect you may not buy into that philosophy ;-)

      Thanks for your comments Cody!