Why Great Functional Specs Are So Important

Way back in the year 2000, the venerable Joel Spolsky wrote a blog post called Painless Functional Specifications – Part 1: Why Bother? It was the first of a four-part series on writing functional specs, and it featured a tale of two software companies: Hasty Bananas Software (HBS) and The Well-Tempered Software Company, a.k.a WellTemperSoft (WTS). Guess which one’s the good one. They both work on the same task of writing a file converter, but WTS does it with a spec and HBS does it without one. Contrived results? Sure:

Total elapsed time for Mr. Rogers [at WTS]: 3 weeks and 1 hour. Elapsed time for Speedy [at HBS]: 4 weeks, but Speedy’s code is not as good.

The story had two morals: functional specs lead to better software design, and they save time communicating:

When you write a spec, you only have to communicate how the program is supposed to work once. Everybody on the team can just read the spec. The QA people read it so that they know how the program is supposed to work and they know what to test for. The marketing people use it to write their vague vaporware white papers to throw up on the web site about products that haven’t been created yet. The business development people misread it to spin weird fantasies about how the product will cure baldness and warts and stuff, but it gets investors, so that’s OK. The developers read it so that they know what code to write. The customers read it to make sure the developers are building a product that they would want to pay for. The technical writers read it and write a nice manual (that gets lost or thrown away, but that’s a different story). The managers read it so that they can look like they know what’s going on in management meetings. And so on.

When you don’t have a spec, all this communication still happens,because it has to, but it happens ad hoc.

Fourteen years later, there came a company called Sprintly, which makes agile project management software. They have a lot of data on how long developer tasks spend in the various stages of the task lifecycle, so they wrote a blog post about it. Turns out, bad functional specs waste a lot of time communicating:

… most of the variability occurs before a ticket has been started (Someday to Backlog). This is the stage when stakeholders are figuring out specs and prioritizing work.

From Sprintly

From Sprintly

In the graph above, the middle two states are when coding is being done. The first and last state are when people are arguing about the specs.

First, Business Bob writes something like “As a human, I want to look at cat videos, so that I’m distracted from writing specs”. Maybe he adds in something about how the videos should play on a mobile phone and not stop to buffer every three seconds. Satisfied with his thoroughness, he emails it to Developer Dave who promptly files it away. Six weeks later he’s ready to tackle the Cat Videos feature, pulls up the spec and realizes it’s so vague that he has no idea where to start. So Dave walks over to Bob’s desk and asks 52 questions:

  1. What format should the videos be in?
  2. Do we want to support multiple bitrates?
  3. Is doing it in HTML5 in the browser fine, or do we have to do Flash too?
  4. Are we hosting these cat videos?
  5. Are we supporting portrait mode on mobile devices?

52. Are we transcoding videos on the fly, or offline?

Business Bob now cringes, realizing what hell he’s gotten himself into, trying to remember why he even wanted the cat videos, and spends the next two days coming up with some decent answers. Except Dave now has follow-ups to those, like what the server hardware specs are gonna be for the video hosts. This goes on for a few more iterations, and Dave finally has a decent spec, so he codes up a storm, then hands it to QA.

Two more weeks later, Tester Tricia pulls up the spec (if you’re following along, we’re now in the last state in the graph above) and takes her turn to terrorize Business Bob:

  1. Should the user be allowed to use multi-touch in the mobile version?
  2. Can the user switch bitrates while playing the video?
  3. Is there a limit on the number of cat videos that can be stored?
  4. What versions of what browsers should be supported?
  5. Are dog videos allowed?

52. What is considered an unacceptable transcoding time?

This is why we can’t have nice things. If Dave did a great job reading Bob’s mind and covered all the bases, maybe the software will pass QA without defects being written against requirements that were changed after the software was written. Sprintly’s data backs up what Joel was saying long ago: unclear and changing requirements eat up developers’ time.

This is why we need great — not good but great — functional specs. It is likely the biggest efficiency gain any software process can make for the cost of a talented spec writer. And that’s key, because that writer will be hard to find.

They need to be technical, ideally have experience writing software (so they know what it’s like to need good specs, and what they entail), be very thorough, detail-oriented, be able to take a lot of criticism, be able to build consensus, to get input and sign-offs from all stakeholders, and most importantly, be a solid writer. Make those specs fun to read, because boring specs make people fall asleep and that’s not good for business.

The last point Sprintly makes is how expensive context switches are, and they link to another classic post by Joel. Turns out that lead developers, who switch contexts a lot, are at least twice as slow at finishing tasks as other developers. So throw out those daily meetings, make coding hours a sacred part of the work day, encourage sparse checking of email, and leave IM chatter for urgent business.

Spolsky must feel like Einstein after Pound-Rebka. Though, more alive.

From Sprintly and Joel on Software, via Slashdot