Documentation: Your Future Best Friend

I have a confession: I like documentation.

I know.

But I have good reasons. Well; some reasons are better than others. I like to type (not really a good reason); I like to write (although I'd argue I'm not all that great at it); and I like to have good references for projects I've done that will hopefully be useful to any future person--or myself--who has to support what I've put together (OK, this is actually a good one).

When talking about data projects or DBA-related work, reference documentation can contain a lot of nitty-gritty information. There are two specific areas that I think are most important, however. The first of these is useful in the case of Business Intelligence projects, and usually takes the form of a combination Data Dictionary/Source-to-Target Mapping listing. The other is in the vein of my post from last week wherein I discussed asking the question of "why" during the early stages of a project. Even having only these "why" question and answers written down can and will go a long way towards painting the picture of a project for the future person needing to support our masterpieces.

As good as it truly is for all people involved in a project, writing reference documentation is something that isn't necessarily easy or a lot of fun to do. One of the most frustrating things about it is that in a lot of instances, time to write this documentation isn't included in the cost or schedule of the project; especially, in my experience, if it's following something like the Scrum methodology. In the case of a "day job", spending time on documentation may not have the same immediate need, as the people who participated on the project theoretically aren't going anywhere. Furthermore, people spending that time takes time away from other work they could be doing. In the case of an outside consultancy, paying an outside firm to sit around and write documentation has an obvious effect on the project's bottom line.

If I had to guess, I'd say most of you readers out there aren't as into documentation as much as I am…I really do understand. But at the same time, what do you do for the future? Do you rely on comments in code or something like Extended Properties on database objects?

And, for those of you that do attempt to provide documentation… do you have to make special efforts to allow the time to create it? Any secrets to winning that argument? ;-)

  • On the topic of just writing stuff down....

    There is the "official" documentation and then there are the personal notes.

    The personal notes I keep are in a simple text file because it can be read from pretty much any environment.

    It lists common "situation" and what to do and contains commands, results, etc.

    It then has the less common situations or issues and how to resolve them as they have been encountered over time.

    In many ways it is more of a cheat sheet, but it gets you through 80% or more of many situations.

    It grows as new situations are encountered.  It evolves as products change...old resolutions are retained in a block with product versions supported in case you go to a shop using an older version.

    A former co-worker didn't believe in documentation.  His name was Cliff.  His documentation has since that time been termed "Cliff Notes - This documentation intentionally left blank".

  • The best documentation is just "writing stuff down" so that you can see it right where you need it. In the code, in a model.  My writing stuff down happens right in the data and UML models.  It's just part of the modeling effort as far as I'm concerned.

  • Personally, I am huge fan of documentation.  I have been known to spend the first weeks of a project or job reviewing and/or rewriting visio diagrams for each of the projects I am assigned to.  Then, I spend time with other teams documenting as well.  I have also mentored many helpdesk and entry level techs on the importance of documentation and to make sure that they are updating the existing documentation and/or creating documentation.  Even simple word documents are better than tribal knowledge.  That is the greatest battle in every company that I have worked with is the removal of tribal knowledge.

    Keep up these posts as I enjoy the intellectual curiosity!

  • Q: Do you rely on comments in code or something like Extended Properties on database objects?

    A: Only when I expect someone to find their way into the code (like me) and it's a little creative or I copy-paste something I didn't read or fully understand.  I always copy the URL of the site(s) I pulled the original code from and put it in the docs right where it's used or, if it's something I fumbled through I put the link to the API docs (or similar) that I read from. Other than that, when coding, it ranges from putting in some comments here an there and documenting command line options to possibly needing to format all comments in functions/methods/classes to a standard so they can be used to auto-generate API documentation, which always feels like an amazing accomplishment.

    Q: And, for those of you that do attempt to provide documentation… do you have to make special efforts to allow the time to create it?

    A: Special effort (for me) is only when taking into consideration people who never perform the work on a daily basis and need procedures. Screenshots are created, little workflows and small descriptions of "why" are needed.

    I also try to spend a little time carving out a "private shared place" for admins to put shared docs in (can be sloppy-er), and a "public shared place" for others that just need process diagrams or lists or non-admin docs.  This is usually a folder/sharepoint area with restricted permissions for admins, then a small set of documents, wiki, or sharepoint site for everyone else.

    Also: If there is a "gotcha" I highlight that part in red *before* the person executes the procedure and right before they actually execute the thing that can cause the gotcha/issue. similar to this:

    Note: This procedure will reboot all app processes and disconnect all users.  Outage normally is about 10 minutes.

    do something x

    do something y

    Note: This is the command that disconnects everyone.

    do something z

    Q: Any secrets to winning that argument? ;-)

    A: Nope.  All my "for users/maangement" documentation hopes and dreams eventually turn into outdated jumbles because nobody updates the documentation, or all updates were communicated via IM or email and everyone stashed them away in their personal documentation area (usually email or their brain).  I also secretly believe that "documentation" is just a standard check mark on some "things we need to do" plans so as soon as you say "yes" to it the box is checked and no one ever looks at it, or planned to look at it.  When someone finally looks at it they see it's >= 6 months old and question it (thankfully) so they don't follow it. Then I have to update it emoticons_sad.png.


  • Excellent--I've had templates before that included this, too. Listing where it came from, who dunnit, quick explanation of the change and where in the doc it is. Great thing to include.

Thwack - Symbolize TM, R, and C