Three Ways to Improve Efficiency With Better Documentation

August 7th, 2013 by

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.

NewImage

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.

NewImage

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)?

NewImage

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.

NewImage

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?

Comments

  1. Stewart Bryson Says:

    Excellent first blog post Jason! I’m looking forward to more content from you.

  2. Mike Vickers Says:

    I like the idea of ‘active’ documentation within each analysis!

    Interested to hear how would you see this being governed within an organisation?

  3. Jitendra Says:

    I liked the idea of publishing “Variables List”, we (developer) had to constantly check “Admin Tool” for updated variables…

    Thank you.
    Looking forward to more posts.

  4. Chris Redgrave Says:

    Great post Jason – particularly like the idea of the documentation for each report. Nicely ominous comment from Stuart too! :)

    Chris

  5. Jason Baer Says:

    @Mike,
    I see the developer notes as being relatively unstructured… comments by developers, for developers.

    There’s nothing stopping you from coming up with a standard format though. For starters, you come up with an outline for the different information you hope to capture, sections for criteria, filters, or whatever. I might even take it one step further… create a new analysis, add that new outline to it, and save that as a “Standard Report Template”. Create all new analyses by opening that template and doing a “Save As” to ensure your outline is used.

    I would caution against making the whole documentation process too complex however. I tend to be a bit of a pessimist, but at least in my experience the more structured you make the documentation process, the less likely it’s followed.

  6. Shruti Says:

    Point 3 – Administration Page concept.. superb :)

  7. Niamh Says:

    Hi Jason,

    Good blog. I think Developer notes are an excellent idea.

    Re the Admin page: What way do you pull the variable names into the analysis? Are they hard coded 1 by 1? I have a similar page just using a text object in a dashboard. But I have a plan to make this more dynamic by exporting the RPD XML and including variables, init block queries etc into an admin table for presentation through OBIEE. But in your opinion is this reinventing wheels? What is the most efficient way to keep the var list out front current and relatively low maintenance?

    Thanks – Niamh
    p.s. on our Admin page, we show some database logging information, last load times, latest timestamps, error flags and sometimes ETL info from ODI log tables etc. Obviously apply with caution and depending on the relevance.

Website Design & Build: tymedia.co.uk