Why Writing Product Specs Is A Waste Of Time

I’ve developed software in two distinct ways: (1) writing very detailed and elaborate specs, or (2) writing very little and instead using lots of pictures and conversations.

There are certainly situations where writing specs seems to make sense, but what I’ve found is that by and large, writing specs in an agile environment can be a complete waste of time.

(Note: There are situations where I’ve found it worth spending time writing things out; specifically, when the process of writing itself helps you clarify in your own mind what you’re trying to do.  I happen to be someone who gains clarity through the writing process — but expecting your engineers to read pages and pages of your precious thoughts is usually a waste of time.)

Here’s the process we’ve found to work; most of the time, we’re using some variation of these steps:

1.  Write User Stories.  The purpose of the User Story is to communicate the main idea and to spark conversation.

We usually write User stories using this format: As a <type of user> I want to <what> so that I can <have some benefit>.  

For example, an important feature to our Clients is the ability to sync their Contacts with SalesForce.com, so a User story might look like “As a Marketer, I want to sync my Contacts with SalesForce.com so that I always have the latest available information for my marketing programs.

Most of our User Stories are one sentence long, and are just enough to create a sense of what we want to do.  That’s it.

Pictures: Worth a thousand words

Pictures: Worth a thousand words

2.  Have conversations.  Using the User Story, we discuss the feature and try to examine it from as many sides as possible.  These sessions usually involve a whiteboard (like the one seen on the right), and we are usually able to get some additional clarity on what needs to be done.  We also share these User Stories with Clients, bouncing ideas off of them and seeking to gain insights we might miss by staying inside the building.

3.  Define Acceptance Criteria.  At some point in the process, we write a specific set of criteria that must be met in order for the feature to be considered “done”.  These are very specific statements that are either true or false.  The Acceptance Criteria are used by engineering (and later, QA) to ensure that what was supposed be done is actually “done”.

4.  Get something minimally working to put your hands on.  It is usually at this point that we begin writing code — whether it be creating a user interface prototype, or actually implementing a raw version of the feature.  The point of this step is to put some flesh on the bones, and to start seeing things come together.  Sometimes it only takes a few hours to get to this point.  Other times, you may need a few days to let things cook.

5.  Give it some love.  Once the feature is working and meets the acceptance criteria, it is helpful to spend some time “loving” the feature.  This means that you make sure that you remove all engineer-speak from the UI (wherever possible), add required help content, and smooth things over as much as possible.  Again, we typically don’t seek to make things perfect, but rather good enough to begin getting feedback from Users.

7.  Put it in the hands of Users.  This is what ultimately matters — getting real-life feedback from the market.  This step is where the real learning begins, and this is why the agile process is so powerful.  It gets you to this point rapidly. If you’ve made a mistake in some core assumptions, you haven’t lost that much time.

8.  Get feedback, and iterate.  As Users interact with the feature, solicit feedback through a variety of methods.  We enjoy speaking with Clients via GoToMeeting, watching them use the feature while at the same time providing us feedback.  We sometimes see them do things we’d never imagine.  Depending on the feedback you receive, you’ll usually loop back to step 2 and continue to refine the feature (if necessary), or give it some time to collect more feedback before deciding to improve it, release it to everyone, or throw it away.  (Yah, it’s ok to throw crap away.  Sometimes things end up sucking!)

Using this process, we’ve managed to save lots of time.  Rather than spend time writing stuff that no one ends up reading in detail, we get our hands dirty creating features that Users give immediate feedback on.

What do you think?  Are writing specs a waste of time?

About David Rosendahl
Husband, father of 4, co-founder of MindFireInc, two-time Inc500 software company. I love building things and helping you generate more leads and grow sales predictably.

3 Responses to Why Writing Product Specs Is A Waste Of Time

  1. postagilist says:

    No, they aren’t a waste of time, because then everyone is on the same page and you can go back and read what was decided on.

    Screenshots are good thing to to have in the document.

    Otherwise the team spends all it’s time asking themselves the same questions over and over again, the team has various different opinions of what the feature supposedly means, etc.

    There is a reason that writing was invented by humans — to solve problems inherent in purely verbal communication 🙂


    • Hi Post Agilist,

      Thanks for the thoughtful comment. It’s great to get contrasting opinions. I visited your blog, and scanned your methodology (http://postagilist.wordpress.com/my-approach/). I can see the benefits of the approach.

      What I outlined is a process that is relatively new for me/us. Historically, we’ve developed using a process similar to what you’ve outlined.

      However, I’ve been (pleasantly) surprised by the method I outlined above.

      Do you think our results would be even better if we were to write more detailed specs?

      Take care,


      PS: Do you mind if I link to your blog from time-to-time to contrast the differences in opinion?

What do you think? Don't hold back.

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: