Today I had to present my detailed design document for an OBIEE project.
The response was...not great. Not even good. So bad, in fact, my boss had to call me afterwards. Fortunately for me, he's a good boss and remembers the good with the bad.
I'm not sure if it is evident, but I'm not afraid to fail. I've done it before, I did it today, I'll do it again in the future. It's just life. As much as I would like to believe (and as much as I tell my wife and kids), I am not perfect. Never have been, never will be.
What should be evident though, through 686 posts here and the untold pages of documentation I have written for wikis, email, groups, blog comments, or some other medium, I don't have a problem with documentation. I like it. I find a lot of value in it. I usually take the lead on it if nothing exists.
Not too long ago I talked about Design Documentation, but that was more of the high level kind. The kind I was expected to deliver today was to be much more in depth. How much more so? Well...
Physical Layer
Each table and the columns that were to be used. This includes aliasing these tables and then their respective joins.
No, that's nothing terrible to ask. I don't argue that.
BMM (Business Model Mapping) Layer
1. I was to have every column defined (both sourced and calculated).
2. Each and every dimension and fact table, including all the Logical Table Sources (LTS) for each of those, including their joins (INNER/OUTER/FULL OUTER), Content, Fragmentation and Leveling defined.
3. The heirarchies (aka dimensions, but not of the table kind) defined by level with all the accompanying columns at each level.
This section gave me the most problems today. While I appreciate the high level design, I felt this encroached a bit on actual development. The more I think about it though, the more reasonable it sounds.
It is a departure for me though.
I tend to develop and design in tandem. Documenting everything up front feels...dirty to me.
Perhaps it's the fact that I was using Word? I mean, seriously, it's 2011. Why are we using binary files? Data should be free!
I prefer wikis. I prefer email over Word. I've used Atlassian products before and think they are great.
Where I have a problem is this (seeming) waterfall approach. How do you know what you don't know?
Then I'm back at the format of the documentation, Word, stored in...ugh...SharePoint. I don't believe I have ever met a less desirable solution. SharePoint is the suck.
Documentation should live and breathe. I have never seen that happen with a Word document. Never. I consider myself somewhat disciplined, and I couldn't fathom maintaining this. Let's make it more narrative (wiki). Let's have a place where the latest and greatest lives, with a possible story of how it got that way. The decisions were made because of A, B and C. You miss most, if not all, of that in the design documents.
Perhaps it's not even Word, or SharePoint. Perhaps it is the process. I'm probably not asking the right questions yet.
To sum it up, I failed today. I have to follow the guidelines set forth...but I can try to influence them...and of course you know I will.
2 comments:
There's always compromise. Build your thoughts in confluence or a wiki. Build your diagrams in a data modeller or Visio.
Then just assemble them into a Word document. Think of it as an EXP. A snapshot of a collection of inter-related components
OMG. I just wrote the word "compromise" in another correspondence. How very weird (to me anyway, I'm an only child, I'm easily amused).
I did do that. I had a physical and logical model in Visio which I just C+P'ed into the Word document.
I just know that after approval, it will never get read again. Meanwhile, the wiki (or CMS or whatever) would live on. Bonus points for allowing the business to view those documents and becoming transparent thus creating a whole new class of smart business people! (I'm an optimist, if you can't tell)
Post a Comment