Detailed Design Documentation
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 LayerEach 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) Layer1. 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.
Labels: documentation, failed, funny, oradb
