Documentation – the difference between a great consultant, and a great consultant who cares…

A great consultant comes in, completes an impossible task with flying colors, wins the day for their sponsor, and leaves. A great consultant, who cares, also leaves behind documentation.

Documentation is most definitely the step child of any IT project. Unfortunately, most developers are either not thoughtful enough about their work to leave behind documentation, or simply don’t like it. Junior developers will document their work, but at a very rudimentary level, which basically equates to going through their code/product and unwinding it. Senior developers are too busy developing interesting “stuff” to be bothered with actually documenting it at a useful level of detail.

Well, as a consultant, I find it highly rewarding to see how much clients appreciate the fact that I always look to leave proper documentation behind, and also take the time to go through it with them. It’s a very simple actually: by leaving behind documentation that can actually help support the work I leave behind, I show that I care. I care about the client, and their long term success. I care enough to put together a deliverable that can serve to explain why I’ve done the things I’ve done (when there’s no doubt there were other ways to do them), how those things actually work, what to do to keep them up and how to extend them.

The same way you wouldn’t want to buy a consumer product with no documentation that explains how to use it, especially if it has any level of complexity bigger than a toothpick (and even those come with instructions on the box), why on earth so many IT, and especially BI, projects end with no proper documentation?

Well, a lot of it has to do with misunderstanding, or uninformed judgment. BI work is often perceived as “creating a report”. Well, modern reports are much closer to applications, then to letter size paper printed reports. They almost always include interactivity and functionality (from prompts to drill downs and navigation), they often rely on complex data that is sourced from multiple sources, they contains code (even reporting application that are GUI driven completely generate code to interact with a data source at some level) as well as visual designs, they incorporate business logic and are expected to address multiple (in some cases hundreds!) or use cases. When you lay all this out, the level of complexity is obvious and obviously merits a diligent effort of documentation, right? Well, the typical response is unfortunately still: “what do you mean you need 4 weeks to document a report???!!!”

Since BI is considered more of an IT discipline then actual software development, it is perceived as more utilitarian and commoditized then the R&D work that any perceives is involved in developing new software. However, BI work is often a lot closer to software development then wiring CAT 5 cables or setting up wireless access points. It always follows some sort of SDLC, includes large cross functional teams (business users, infrastructure, database developers, reports/applications developers…), and a high degree of creativity. Especially since most BI projects start out with high level vague requirements and evolve as they progress.

So, next time you work on a BI project, be sure to set aside some time to properly document your work. If for no other reason, your clients (internal or external) will love you for that, and will certainly take that into consideration when thinking about working with you again.

This entry was posted in BI At Large and tagged , , , . Bookmark the permalink.

2 Responses to Documentation – the difference between a great consultant, and a great consultant who cares…

  1. AnuSh says:


    I read your blog post and completely agree with what you have mentioned. I am a new technical writer and have been given the task to document data dictionary. The users access data through the cube via excel. The data fields are complex, most of the non-technical users does not understand the cube terminology.

    How can I display the data dictionary in a easy to use manner where users understand what data resides in the cube and what is means.

    I really need help in this. Any help would be much appreciated. Thanks for your time.


    • Ron Keler says:

      AnuSh, many products provide “build in” data dictionary capabilities. I suggest you explore the capabilities of the technology the cube has been implemented in. Also, your database folks should be able to provide you with a “meta data” dump of all the fields and hierarchies in the cube, which you could organize in an excel spreadsheet with descriptions.

Leave a Reply

Your email address will not be published. Required fields are marked *