Three Ways to Improve Efficiency With Better Documentation

I was at a client site recently, and as part of a front-end development effort we had added some documentation within the web catalog. They had never seen anything like it and started referring to it as “smart” documentation. Quite frankly, I was more than a bit taken aback by all the positive reactions. I didn’t start out in the field of business intelligence and analytics; I got my start as a software developer programming in C, C++, and Java. In software development, commenting your work was expected… it was just something you did. In the world of dashboards and analyses however, more often than not, documenting your work proves to be the exception and not the norm. It tends to be an afterthought and even then it’s usually shoved into some document stored in an obscure shared drive that no ever has time to update.

But that shouldn’t be the case! Don’t get me wrong, I don’t find documentation all that exciting. “Hate” is a strong word, but I for one certainly don’t “enjoy” documenting. I haven’t come across all that many technologists that do. But I also don’t enjoy repeatedly answering the same questions time and time again; and I don’t enjoy endlessly maintaining projects (one of the draws of consulting is that each project has a finite end). But, if there is one thing I truly hate, it’s doing things twice.

I like efficiency. And in my experience, smart documentation leads to efficiency.

1. Naming conventions. This one’s a no-brainer. Before you start developing anything, put some thought into how your objects will be named and organized. Give the objects in your web catalog a logical name and group them in a way that makes sense. If someone new joins the development team and the analyses are all named Finance Report 1, Finance Report 2, etc. how are they supposed to determine what’s what? Hopefully I’m exaggerating, but you get the idea. Everything should have a semantic name that gives a bit of insight into what its purpose is.

I like to set up my web catalog with a folder for each object type (e.g. a folder for Analyses, Prompts, Actions, etc.). I might also prepend the name of the dashboard to the name of the analysis. To me, this makes total sense. At a glance, anyone can figure out where to look for a particular object.

This might not work everywhere.  We typically migrate an entire subject area at once, however, if you migrate individual dashboards you’ll want to organize your catalog differently.  Every company, every implementation, even every project is different.  There is no one hard and fast rule with regard to naming conventions.  The real point I want to make is to set up some naming standards and enforce them.

2. Developer Notes. I make it a point to create a Static Text view within each and every analysis I create. I rename the view to “Developer Notes” and jot down a few words for anything that might become a question later on, especially if I think I might question what was done later on. Explain the logic behind any complex filters you’ve used, how conditional formatting has been set up, why certain columns appear as part of the criteria, etc. Organize the notes enough that someone won’t have to read it in its entirety to make some basic modifications, but otherwise don’t spend a whole lot of time worrying about the format. I promise that this will save you time down the road and it shouldn’t take more than a few minutes time.

I don’t typically add this to the compound layout, it’s generally not something I want all the users to see.  But later on if I need to see my notes I can add them in just a few clicks from the Edit Dashboard screen.

Case in point… we’ve all used conditional formatting, it’s a great tool to highlight certain information.  Personally, I like to use conditional formatting to highlight certain information based upon a value in a particular column.  But, do you know what happens if that column is removed (which could easily happen especially if you have a shared environment with multiple developers)?

And there’s no easy way to “undo” either. Within the XML the columns are referenced using a hashed ID, so you can’t just add the column back in. You’d need to either roll back to a saved version, recreate the conditional formatting from scratch, or manually make changes to the XML.

But not to worry, if I just include a sentence or two in the developer notes, I could let everyone know not to remove this column for any reason. Make it a standard operating procedure when working with other developers that everyone should at least glance through the developer notes prior to making any modifications.

3. Administration Page. How often do you need to look up a variable or create a quick analysis to verify the value of a variable? It’s not a big of a deal if you have access to the Admin tool, but maybe you don’t. Or maybe you have access to the Admin tool and others don’t… do they constantly pester you for what variables are available? There’s no reason to hoard all this information; empower your users. Give them an administration page with all this information so they can figure it out for themselves and by doing so, you’ve streamlined the entire process. Create an analysis that contains all your important variables. Provide the appropriate variable name and save. Throw that on a separate Administration dashboard page, secure it to your developers if you wish, and you’re good to go.

While you’re at it, put together some notes around your naming standards and stash that out on the dashboard as well!

What are some of the ways you document your web catalog?