How To Play

This is a difficult one for me to frame, but I'll do my best. I know the community here will have some good ideas.

I started working with a new client about a month ago. They're a well known commercial and personal insurance company in the US. I've worked in and around the insurance industry a lot since 1990, so I know the culture (very conservative). For the better part of the early 1990s I worked at INSTEC, which was -- and still is to my knowledge -- the largest producer of commercial insurance rating applications.

The reason this client brought me in was a) their lack of Java and O-O knowledge, and b) I've had a lot of experience with document management systems such as FileNet and Documentum. This client happens to be using Documentum. That's really an aside. They put a lot of value on that knowledge but, to be honest, any competent programmer can learn the nuts and bolts of any document management system in a few weeks or less.

This company has separate teams for everything. I'm in the Enterprise Content Management group but there's also a Configuration/Change Management group, a "build" group, and an architecture group. If you're beginning to whif the smells, keep reading. Since this is an insurance company they have some rather strict audit requirements for their software development. I'd say almost 100% of these are documentation related; code is very low on the list. Very backwards, but -- it's what I have to work with. To my mind there are a multitude of ways these audit requirements could be met, but that's another discussion for another day.

The first project I've been given is to provide the Configuration Management team a web front-end to Documentum for their "Central Repository" of documentation. They already have a nice twenty page requirements document written up that is quite detailed. And now I segue into my problem ... one of the managers here is trying to get everyone onto the RUP bandwagon. However, they're not doing RUP here. It's waterfall all the way; they're just calling it RUP. Needless to say, for this one little project that I estimated would take me three weeks to code, they want me to write forty documents. I won't go into the absurdity of some of these documents, but if you're at all familiar with RUP you'll know some of them. The sad part is that RUP does not require all of these documents, all of the time. Further, they're going through the entire requirements phase again writing use cases instead of just working from the requirements document they already have.

I cheated. I wrote the damn system; it's done. It took me exactly three weeks, just like I had scheduled. (I've done enough of these that I'm getting really good at estimating the time it takes). However, from the beginning, I've sensed a certain potential conflict with the manager of this group. I hear frequently, "Don't write any code until the documentation is done." This scares me.

My problem is two-fold:

a) The documentation I'm writing doesn't match, exactly, what I've produced. However, the application I've produced meets all of the requirements.

b) I don't know how to tell this client that I'm done and they can have their testers write scripts and test the damn thing.

I showed the application to only one other programmer here and he was in awe. We spent nearly an hour going over the architecture and he was soaking up all sorts of good information. That's great; however, I don't think management will have the same response.

How do I proceed? How do I tell all of the stakeholders involved without burning some of them in the process? I ask this last question because the "published" schedule is four months! I'm done; it took three weeks. This isn't going to look good for certain managers in our group.

Do I PlayHurt or publish reality and suffer the consequences? -- JeffPanici

As a follow up, I presented both the working prototype and all of the documentation -- in the formats they like. The result? Not great. Within a day I was on another team, working on another project. As I feared, this made one manager look very bad to their customer (this is an internal customer). As near as I can could tell in the "final meeting", the customer was very anxious to see what I'd built. However, this manager was hell bent on preventing that from happening. This manager would spout things like, "We must follow procedure." and "I like to do paper prototypes first." It was one massive circle-jerk. A few days ago I bumped into one of the customer representatives and they said, "I'd still like to see what you built. The project is stalled and they're [the group I was in] writing the documentation again."

To be clear, the customer approved all of the documentation I had produced and it was ultimately their role to do so. The part that scares me about all of this is it's becoming a constant thing. It's like all companies are adopting DeliveryIsNotTheGoal. I'm about to give up. -- JeffPanici

I advise always siding with reality. Reality may hurt some of the managers. However, the alternative is to allow these people to continue living in a fantasy world. That's not right.

Judging from your comments, nothing will be hurt if you write all the required documents. I suggest writing the documentation, then presenting the whole thing, even if that's three months ahead of schedule.

It's certainly not your fault if some of your co-workers are out of touch.

-- BrentNewhall