Skip to content

Stop writing specs, co-located feature crews

 I’m not a Program Manager (PM). I’ve never been a PM. I’m not likely to ever become a PM. It’s nothing personal against program managers. I’ve known great ones I count among my friends. I certainly have no right to tell PMs how to do their jobs.

That said, PMs should stop writing specs. Period. They are wasting my time; they are wasting my group’s time; and they are wasting the company’s time. You can almost hear the sound of quiet residual crunching as spec termites chew away at company and customer value. It makes me nauseous.

It’s not just PMs though. Developers need to stop writing dev specs. Testers need to stop writing test specs. The madness must stop. The waste must stop. We must regain our senses and take back our productivity, along with our sanity.

Eric AsideThis column was easily among my most contentious in terms of response. As you can see in the next paragraph, I guessed it would be. The biggest misunderstanding about my message was the difference between formal and informal documentation. I argue that co-located, cross-discipline teams need only informal documentation, like photos of whiteboards stored on a wiki with some minimal commentary. Teams divided by distance or discipline need formal documentation, like detailed specifications.

Have you lost your mind?

“Surely you can’t be serious?” I hear my conscientious readers say. “You’ve been preaching quality (see Where’s the beef? Why we need quality) and design (see Resolved by design) for years. You’ve been telling devs not to act before they have the spec and not to code before they’ve thought through the design. Are you saying you were misguided, or even, perhaps, wrong?” No, of course not.

Feature teams must understand the user experience before they create it, and devs must understand the internal design enough to explain it with a straight face to peers before they implement it. But neither of those steps requires formal written documentation.

Why do we have formal written specs? Customers don’t need them. Marketing and product planning groups don’t need them. Even content publishers and product support get limited use from specs. So who needs these wanton wonders of waste? To find out, throw specs away and see who screams.

Therein lies a dilemma

If we no longer had specs, devs and testers would cry, “How am I supposed to know what the code should do?” Tell them to discuss it with PMs and they’d holler, “PMs don’t just hang around my office all day. I need specs written down. I need to review them, change them, and update them.”

Ah yes, there’s the rub. Not that devs and testers need to review, change, and update specs, but that PMs don’t hang around to discuss the user experience, implementation, and test strategy all day. Well, what if they did?

What if PMs stayed all day in the same open area surrounded by whiteboards with devs and testers who were working on the same feature set? Would we still need formal written specs? Wait, I hear more screaming.

Special needs

Without formal written specs, teams that depend on features from other teams would protest, “How are we supposed to use your code if we don’t know how it works?” Good point. If PMs are hanging around the feature team all day, they can’t also be on call with all the downstream teams, and we can’t fit everyone into the same team room. However, downstream teams don’t need a spec—they need a mini-SDK, which component teams should be providing anyway, and which adds great value.

Without formal written specs, the compliance police would bark, “Where’s the <insert your favorite bureaucratic suppository here> document?” Another good point. The compliance police keep us out of harm’s way. It’s an important if thankless job, and they often require formal written documentation to do it. However, the compliance police don’t need a spec either. They need complete compliance documentation, which often has different information in a different form than a spec.

Eric AsideWho are these “compliance police”? They are regular engineers who focus on key areas Microsoft must ensure are correct in our products, such as security, privacy, world readiness (no inappropriate euphemisms or references), and compliance with all applicable laws and regulations. Examples of typical documentation they require include threat models (security), privacy statements, and licensing terms.

In both cases, you don’t need formal written specs. Instead, you need specialized documentation that is easier to write because it’s not open-ended.

I don’t recall

So do we still need formal written specs? I can’t remember all the cases, so let’s recap:

  • PMs spend their days in the team room discussing the user experience, implementation, and test strategy with the feature team.
  • The team writes mini-SDKs for downstream teams.
  • The team fills out required compliance documentation.

It’s good that I wrote that down. Oh wait, that’s a problem.

People are forgetful. You’ve got to write ideas down, particularly when you are constantly switching between projects. Naturally, if a feature takes months from start to finish you might even have people leave the team and lose the information entirely.

Stick to one thing

But what if you worked on only one feature at a time? Then it wouldn’t take as long, and you wouldn’t be switching between projects. There would be little chance of anyone leaving, and remembering ideas would be much easier. You’d just need to capture whatever was on the whiteboards with a digital camera and paste it into a wiki, Word document, or OneNote notebook.

It’s like having specs, only without the mind-numbing tedium. That leaves you more time to think and collaborate at the whiteboard, and less time at your desk pushing pixels and words around.

Okay, you keep the feature team in close quarters with lots of whiteboards. You work on one feature at a time till it’s done, documenting your decisions with a camera. You write specially targeted documents that add value downstream. This sounds like Lean software development (which you can read more about in the article Lean: More than good pastrami). Bingo! That’s what you get when you cut out the waste.

You ready?

Very few teams could stop writing formal specs tomorrow. They haven’t adopted the feature crew concept of working on one feature at a time from start to finish, and they aren’t co-located in a team room with whiteboards.

However, that’s starting to change. Groups are co-locating because it’s faster and easier to get work done. Groups are forming feature crews because you get higher quality faster and leave behind less incomplete work. Take those trends, put them together, and you can kiss specs goodbye forever. It’s more than a dream; it’s a homecoming to simpler days, but with the wisdom gained by years of hard-fought experience.

Eric AsideMy first tricky project as development manager for the team was to co-locate the six scrum teams, including removing the cubical walls within each team room. Those six teams had been operating on the same big release for Kinect and Windows Phone for several months before the office shuffle, and several months after the shuffle. The timing and all the team velocity data that Scrum provides made this a great opportunity to measure the impact of co-location. The four-week average velocity for five of the six teams increased between 20% and 63% (the sixth team was releasing a beta and halted new development). That 20% increase is like getting an extra day a week of productivity and still having a two-day weekend. The team that increased 63% (that’s three extra days a week!) also decreased the size of their stories, left stories unassigned so that the first available person could pick them up, and increased cross-discipline pairing for stories with many unknowns. The only documenting the teams did was maintaining OneNote notebooks and completing the essential compliance work.

Published inUncategorized

Be First to Comment

Your take?

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: