How much detail should go in the spec? How much should be figured out before starting dev work? My engineers keep telling me not enough is figured out, so they can't start working on my thing. HALP ME ERIN.

—Krampus

Dear Krampus,

Ahh, this is such a great question, and one that may require several posts to cover. Nevertheless, let me give this a try.

Rage against the spec

I really, honestly, dislike the term and even the concept of a “spec” so much. Typically a spec is structured as a document written entirely by the product manager that lays out all of the product “requirements” for the rest of the team to follow. It walks the engineers through exactly what and how the product should work, and leaves only the implementation details up to the engineering team.

This is a really, really dated concept. It much more closely resembles the typical IT partner process that happens in large companies. I know this because I was that person for 6.5 years. Now, it’s entirely possible IT project management has changed in the 8 years since I left it, but nevertheless is a really helpful comparison for me.

System of a spec

In the spec universe, we ask our customers or business partners what they need. We determine everything that they will need in the foreseeable future, and we write those requirements into a multi-page document. We write out test cases that should cover every possible permutation of actions a user could take. We get THE ONE design to rule them all. And then we hand it over to engineering and ask them how long it’s going to take.

This is what we like to call “waterfall” development. Waterfall has its place—for example, if you’re building aircraft engines, it’s probably for the best that you have long-term plans—but that place is not in a small or midsize software company.

Alternative systems

In the problem universe, we ask our customers what they need. Then we ask them why they need it, and what they’re actually trying to accomplish. We throw out the thing they asked for and instead concentrate on the outcome they desire. We write out those problems and relevant constraints, and we only look at the most important ones. We collaborate with a team of designers and engineers to dream up the best possible solutions to those problems, and we then write those solutions up as user stories.

This is targeted, collaborative, and modular. If something changes, rather than updating a long out-dated document and determining how the change cascades through all of our hard-laid plans, we simply delete one story, and replace it. We simply de-prioritize one story, and move two others above.

The connotation of spec

There are additional reasons to avoid the use of even the word “spec.” Some may call this semantics, but in a world where we are leading and influencing a group of smart, opinionated engineers to pursue a vision, semantics matter. So much of leadership comes down to understanding the nuances is which words you use, and how you use them.

The word spec means, quite literally, specifications. Requirements. Things that should be followed exactly. If you build something to spec, you build something that exactly matches the requirements. There’s typically not a whole lot of creativity involved, or room to come up with something that’s better than the spec. 

Master of solutions

If your engineers are telling you not enough is figured out and you don’t know what needs to be figured out, I’d suggest booking a room for half a day and hashing it out with them. There is definitely an amount of product ideation, story-writing, and technical exploration needed before diving in, and that needs to happen at the team level. The team doesn’t need you to flesh it out yourself, but they might need you to lead them through the process of figuring that out.

Here are some questions to ask yourself:

• Does your team fully understand the problems they’re setting out to solve?

• Have you and your team already drawn up a rough agreed upon solution?

• Has your designer contributed lo-fi designs that support that solution?

• Has your team walked through proposed business logic and identified edge cases?

• Does your team have enough of an idea of the solution to:

  • Research required technologies?

  • Design the database?

  • Design the APIs?

  • Articulate what could be delivered in a phase one?

There’s a good chance that if they’re stuck, you probably haven’t spent enough time with the team addressing these questions. Remember, you don’t have to come up with the solution or edge cases or anything else on your own. But you do have to facilitate the process.

You’re gonna go far, PM

Remember the tools of our trade, and you’re going to be just fine.

• Make sure your tripod is set up

• Get to the heart of the problem & create a problem page

• Have a sketch session with your team to collaborate on a solution

• Have follow-up sessions to flesh out core product logic

• Write great stories

You’ve got this, Krampus.
Erin