Thursday, February 17, 2011

Design Documentation

I got bit recently. I didn't ask for requirements and I didn't create a design document. Bad Chet.

It made for a difficult time getting that first cut done...and I missed a few very important items.

Talking with a friend today about it, and he kind of hammered the point home. Do the design document and you spend fewer cycles spinning your wheels. As an example he use a project we both worked on last summer. At first, he didn't do a design document and "struggled" for a couple of weeks. When it came time to do it again (it had been dropped from that first release), he started with the design document and it only took a week.

Forced him to think about how to do it, the possible roadblocks and the ability to raise those roadblocks to the appropriate people.

For whatever reason, I had never thought of the design document in terms of OBIEE. I don't know why, it just was. For OLTP type applications, I would always, at a minimum, create a Visio diagram. That would allow me to quickly and easily spot any problems. That world is much more intuitive to me, so I can visualize it easier. OBIEE, not as easy.

So here's my pledge to, no matter how much I loathe formal design documents, to go forth and create formal design documents. After all, this is development, just a different tool (and a layer of abstraction). No more ad-hoc development for me.


Jake said...

You could take an agile approach and build something first, document it and then iterate.

The problem with a design document is that it feels very final, which is why most people loath documentation in general.

oraclenerd said...

That is typically what I do, build then document (usually a wiki) (and usually on my own, as most places don't do documentation).

That "final" thing is what throws me. Feels like a big waste of time as no one will ever read or update it after it has been "completed."

Most of my Visio diagrams go untouched, despite my best intentions, after the initial creation. That's why I don't spend a lot of time on perfecting them. I just need a quick and dirty visual.

Joel Garry said...

You'd think our computer overlords would give us tools to go back and forth between code and design documents by now.