I had an amazing revelation at work last week.

At my previous job, the company culture steadfastly clung to the waterfall model as the one true way to develop software. The model was imposed as a series of documents with cryptic, archaic acronyms for names. I actually had to draw a flowchart for my team to help them keep track of when each document was required in the life cycle of an enhancement request.

No code was changed in our code-base without a minimum of literally five separate documents, each usually spanning tens of pages. Project managers at the company enforced the production of these documents in a near-religious deference to “the process.” Each document was reviewed, often via conference call, to receive it’s “stamp of approval” (basically a C.Y.A. cross-check) among the affected teams (usually development, production support, professional services, client management, security, perhaps others).

It often felt as though I worked at a documentation company that happened to create software as a by-product.

It was in this atmosphere that I first started reading about so-called Agile methodologies. Iterative prototyping, unit testing, and tight user/developer communications, their practitioners argued, were a more effective way to deliver software that met customer expectations. Because specifications change, and users don’t know what they want, you’re already behind schedule by the time you get done with all of that front-end junk.

It all sounded so wonderful – too good to be true. If only my company were more like that.

Now I’m at a new job. There’s very little process here – it goes something like this: A nominal business analyst creates a document with a punch-list of specifications, and the developers go off and implement it. That’s it.

You’d think I was in paradise! I would be freed of the shackles of Microsoft Word, and I’d be able to churn out code as efficiently as possible.

What Really Happened
I soon discovered myself going in circles. I’d spend a lot of time in front of the whiteboard drawing ERDs for the database, and then I wouldn’t know where to go next. Start Object-Relational mapping? Hmm… seems to soon for that. The business model? And what is the business model… what does it need to do? And will the business model’s persistent data be adequately served by the data model on this white board?

Maybe I’ll just dive in and start implementing… Agile-style. I guess that means I should start with the UI; how do I do the UI? That’s what the user wants, right? The spec says I need to do such-and-such… I know! I’ll crate a UI, and wire it up to the model’s interface, and mock-out the actual implementation of the model! So there’s really no ugly business model code to worry about.

So what should the model’s API’s be? What parameters do I need to pass around to make this thing re-usable? Will I end up needing to refactor the whole thing to support some relationship I haven’t considered yet? Oh well. Don’t worry about that for now.

And, by the way, the UI is just an admistrative, ancillary part of this project. It’s actually a batch process that runs nightly which is configured via the UI. The UI isn’t even technically necessary. Am I putting the proverbial cart before the horse? Hmmph – probably I shouldn’t start with the UI, then.

Hey – look at this whiteboard… an ERD… let’s work on that for a while!

What Works for Me
What was actually wrong with my old job was the sheer volume of documentation, and the ratio of useful information to the total number of pages. That documentation was almost never for me – it was for other people (although I still wonder how valuable it really was to other people).

Personally, I need something to ground the project. I need a place to organize my thoughts. For me, a “specification” isn’t a giant UML class diagram that I slavishly adhere to, and keep in sync with the code at all times. It’s a place where I enumerate the affected components, discover how they interact, and itemize the work that needs to be done. It’s where I validate that the thing I’m about to build is going to come somewhat close to meeting the user’s expectations.

Sometimes, I share the document with other people. Sometimes I don’t. But I’ve learned that personally, for me, I need a place to focus, and collect the pieces that need to interact, before I start writing.

For some reason, this was an amazing revelation to me. My experience at my last job had led me to believe that I was firmly in the anti-documentation camp. It turns out that, in my case, that wasn’t true at all. I need some documentation. And I don’t think it’s true for everybody, either. I’m sure there are people who are better at diving right in, and still others that want even more documentation than I do.

What works for you?
Photo Credit: Fredrik Lundh

This entry was posted on Wednesday, May 28th, 2008 at 8:30 pm and is filed under career, programming. You can follow any responses to this entry through the RSS 2.0 feed. Both comments and pings are currently closed.