You’ve hit code complete, you’re burning the bugs, when what arrives in your Inbox? Look, oh joy, it’s a new spec! Punt it, right? But wait, it’s a key feature that you figured was spec-less, or as we often like to say, “The code is the spec.”
Eric Aside A feature is code complete when the developer believes all the code necessary to implement the feature has been checked into source control. Often this is a judgment call, but on better teams it’s actually measured based on quality criteria (at which point it’s often called “feature complete”).
Of course, test is now furious because they didn’t get the spec earlier and feel “out of the loop,” it’s too late, the code doesn’t match, and they haven’t tested it. Dev is upset because feature work was supposed to be finished, test is now mad at them for coding the “wrong” thing, there’s a ton of rework to do, and what’s worse, dev has been caught coding an improperly documented feature. It gets even more pleasant as people argue over the new spec, find holes, make changes, and basically churn the code to death at the very time it should be stabilizing.
For every change, churn, churn, churn
An extreme example, perhaps, but it’s happened, probably more than once. Even if they aren’t that late, specs often are incomplete or aren’t reviewed and inspected in time for dev to start work.
So what happens? Churn, and lots of it. Dev starts coding too early. The spec has issues, so the code has issues. Someone points these out, ad hoc meetings are held, someone gets left out, the code is reworked, whoever was left out finds something else wrong, there are more ad hoc meetings, and so it goes.
What can be done about this? Some folks might say, “PMs are scum, persecute them till they produce.” Even for me, that seems harsh. Specs come in late; it’s a fact of life. The question is how you deal with it. I’ve seen a few different approaches.
Eric Aside I know eXtreme Programming buffs out there are yelling, “Get a room!” (a team room). I make the same argument in a later column, “Stop writing specs, co-located feature crews.” However, Microsoft is a fairly diverse environment. Not every team can co-locate, and dependencies often make documentation a must, so we need more than one solution.
Hallway meetings
The first approach is the hallway meeting. A dev finds holes in the currently available spec and sees a PM passing by. A hallway meeting commences; some issues are worked out. The dev goes happily back to her desk thinking she now knows the right thing to do. The PM goes back to his office thinking the code will reflect what he wanted. Maybe they are thinking the same thing, maybe not. Maybe test and ops would agree with the solution, maybe not. Maybe they thought of everything, maybe they didn’t. Maybe this is the best way to handle changes, maybe monkeys will fly out of my… well, you get the idea.
Committee meetings
A second approach is the committee meeting. It goes by other names on other teams, but it’s basically a leads’ meeting to discuss spec changes. Often they’re held on a regular basis, and the group of leads gets together to talk about holes or problem areas in the specs and work out solutions as a group. The lead PM writes up the results and mails them out to the whole team.
The good news: committee meetings include the right folks, come to final decisions, and then document and communicate those decisions to the team. The bad news: committee meetings are a frigging nightmare. They are long, painful, and exhausting. They use up huge cycles of critical resources. They block progress and form the worst kind of bottleneck—self-inflicted and self-perpetuating.
Spec change requests
The approach I like most is the spec change request (SCR), also known as a design change request (DCR) with a twist. It’s a combination of the committee meeting and hallway meeting with a few key differences. You start with an idea of how you’d like to change or add to a spec. Maybe you arrived at the idea on your own, maybe through a hallway conversation, maybe through a leads’ meeting.
Regardless of whether you’re the PM, dev, test, or ops, you write up the idea in an e-mail with the subject line “SCR: <affected spec> – <short description of change>.” You end the e-mail with these words in bold, “Unless there are strong objections, this is now considered spec.” Then you send it to the PM, dev, test, and ops folks who are most directly affected by the change. A few days later, after adding whatever alterations are suggested by peers, you send it to the rest of the team and track it with other SCRs in RAID and/or a public folder.
The key is that the change is documented and reviewed but does not block progress. Objections are almost always the exception, not the rule. The dev can proceed whenever she likes, trading risk of objections against time. Typically, a dev waits till the SCR is sent to the full team after the initial alterations.
Prevention is the best cure
Of course, the best thing is for a spec not to be late in the first place or at least for it not to blindside you. That’s where T-I-M-E Charting can help. In T-I-M-E Charting, the first spec lays out the design of the entire project. Not simply a requirements document, not a set of mini-specs, but a high-level spec of the project much like a high-level architecture document a dev lead might write. It should lay out what functions and UI the project will have and how they will act together, leaving details for later specs. All future specs and features should be referred to by the first high-level spec.
Now dev, test, and ops, can make plans that account for all future features. They can make a better integrated product that feels smoother to the user. PMs can also use the first spec to schedule the rest of the specs, hitting the high-priority ones first, without worrying about missing something or surprising someone. It’s an idea whose T-I-M-E has come (couldn’t resist).
Eric Aside Totally Inclusive Mutually Exclusive (T-I-M-E) Charting, from Donald Wood, never quite caught on in the form that a peer of mine, Rick Andrews, originally envisioned it. However, value propositions, vision documents, cross-product scenarios, and thoughtfully designed prototypes now serve the same purpose.
Be First to Comment