The Value of Documentation

BY ALEX TATIYANTS

March 24th, 2011

Devs often talk about the importance of documentation. More specifically, they usually complain about systems which have none (“How are we supposed to know what’s going on here?!“), some (“Well, I guess something is better than nothing, but come on!“), or lots (“Are you really expecting me to read all this?!“).

I was once in an agile training class when the issue of documentation came up. The instructor asked whether we thought documentation was important. The responses were a mix, but one guy in particular was adamant that documentation isn’t necessary at all. When asked why he simply said: “Well, I’m a developer and I never read it“.

Interestingly, even though devs generally dislike reading documentation, they often ask for it. That’s because when devs ask for documentation, what they’re really asking for is an answer to two questions:

  1. I want to know what the system is supposed to do
  2. I want to understand why the system was implemented in this way

What is this thing supposed to do?

Ideally, a system would have a requirements document describing behaviors implemented within it. To be especially useful, this document would be specific enough to address implementation details. And of course, it would be up to date.

Bad news is that creating this document as a document is next to pointless because the effort required to maintain it is prohibitively high for most systems. Good news is that a well-written set of functional tests can probably serve a similar purpose and be automatically up-to-date at the same time.

Why does it work like this?

This one is trickier. Again, ideally there would be some living “decisions” document describing the thought process behind major architectural decisions, algorithms, etc. And again, the cost of maintaining such a document would probably make it not viable. There are a few things that could help:

This would improve the sexual life of that person in the same way it works for the sole purpose that is to improve the blood flow to the male reproductive organ. http://appalachianmagazine.com/2017/12/28/extreme-cold-temperatures-place-pipes-at-risk-of-freezing-how-to-prevent-this-from-happening/ viagra no prescription It is also very important that an instructor should teach the learner driving step viagra purchase uk by step. Frequently, detection of type 2 diabetes is made only when significant complications arise or even during routine pathological lab generic cialis pills tests. Many people happen to be embarrassed about their particular human body. tadalafil uk

Final Thought

I don’t mean to imply that written documentation is entirely useless. As long as you can address the issue of staleness, written documentation could actually be helpful. There are teams, for example, that are using wikis to share knowledge with pretty good success.

You may also like:

Did you love / hate / were unmoved by this post?
Then show your support / disgust / indifference by following me on Twitter!

This post got 4 comments so far. Care to add yours?

  1. Kishore says:
    April 3, 2011 at 8:09 pm

    I am still a firm believer of documentation. I know most of the developers hate “documentation”, and it has become rather a cliche to publically oppose documentation, and feel proud about it. But end of the day, almost everyone “depend” on some kind of documentation. That is the truth.

    Imagine, how this world of IT would have been, if there was absolutely no documentation?

    • Alex Tatiyants says:
      April 4, 2011 at 3:37 am

      Hi Kishore, thank you very much for your comment. I don’t disagree that some form of documentation is necessary. However, I do believe that traditional written documentation has the tendency to get stale, which makes its value limited.

  2. JasonK says:
    January 14, 2012 at 2:49 pm

    The third question being asked when asking for documentation on a system is

    Do you know what the heck you are doing?

    This question may arise when coming in on a ‘failing’ project. The documentation helps get you up to speed, but also shows the path that the development took and lack of it may indicate a lack of thought in key design decisions.

    I believe in documentation as thought exercise for major design decisions before and as you go so that the ‘why’ can be captured if not always the ‘how’. I think it is something that is maintainable, and if if not always up to date the genesis of design decisions is also important to understand. Plus when working in dynamic teams where engineers can get pulled off and put on to systems in little time, documentation of these design decisions helps increase the coherency in the code.