Apparently it's going to be business intelligence week on my blog, since this entry on my fifth rule of business intelligence makes three in a row* on the subject. This time, I'm going to give you the rule right up front: documentation must be a requirement of BI development, not an option.
This might seem like a no-brainer -- if you've never worked in an actual IT or operations department.
In a decidedly non-scientific method of evaluation,** I'm going to hazard a guess that documentation is considered a "nice to have" in about 99% of BI (and general IT) operations. More specifically, documentation is an activity that leadership and management teams typically refuse to budget time for, yet lament the lack of when things aren't so clear later. The strongest adherence to a culture of good documentation tends to be found in project management, but there's far more to documentation than just the project charter, Gantt charts, and status reports.
On the developer-facing side you've got data source, acquisition, and transformation information. Development standards, style guides, platform strategy and history, data governance, retention policies, and relationship models. Facing the end user, you've got business rules references, metric and KPI guides, subject overviews, and access policies. And that's just a short list -- there are far more subjects that need quality documentation in order for your data to become a usable information asset.
Predictability is one of the major focal points as a BI matures. Every stakeholder wants to know when his or her request*** will be ready. The BI team and vendor resources grow more rigorous about organizing development into sprints, performing VROMs, and predicting the number of hours for each task. And that prediction rarely includes thorough, high-quality documentation.
After all, time is money, and it's bad enough the world has to wait 20 person-hours for that next customer satisfaction report. Two more hours for governance and documentation?**** If we just forego those activities on the next ten projects, we could accomplish an additional project in the "time saved!" We'll come back and document everything when we have some "breathing room."
Breathing room, of course, tends to occur on the 20th of Never.
Even in the one-man show of my NFL analysis I keep a rudimentary set of documentation. A field name that seems quite descriptive today can be ambiguous in a very short time of non-use. The couple of minutes I spend tracking notes in OneNote or Excel are time better spent than an hour of reverse-engineering my code later, or worse, sharing incorrect analysis because I forgot a definition.
Rudimentary, sure, but sufficient for preventing mistakes and saving time in future development.
Ever wonder why the FDA requires ingredients to be listed on food packaging? It's so you can understand what's in your food, and avoid making bad decisions. Sure, people still make plenty of bad dietary decisions, but with better information, they have a better chance of making a good decision. No one ever looks at a Cheeto and says, "Wow, a bag of these will help me lose weight!"
In BI, lack of documentation or low-quality documentation precipitates significant mistakes. A developer can create a new measure with an incorrect calculation. Stakeholders can waste time debating results because their definitions of KPIs differs. Incorrect information can be issued publicly, or to external customers.
The solution is simple. Change the culture of your organization such that proper documentation is part of the development process. Budget the time and resources to include documentation activities. Don't allow the process to be put off until that non-extant breathing room appears. And once that high-quality meta-information is available, try reading the side of the package every once in a while.
* That's right, a perfect 5 for 7!
** I.e., my gut feel after 20 years in this discipline.
*** Keep in mind that each stakeholder's current request is always the most crucial, make-or-break-our-business request in the history of the company. And Earth itself.
**** Next you're going to be demanding bathroom breaks!
