// I need to

ModernizeUpgrade without breaking it RescueFix what someone else started Build NewTurn an idea into a product Reach More PeopleGet found, get used, include everyone

// Company

Case StudiesExpertiseAbout + CareersResourcesContact Book a call →

Thoughts on Writing Software Requirements

Writing software requirements is painful and unhip, but essential. The benefits for developers and clients, and practical tips for writing specs.

Art+Logic Mar 17, 20143 min read

From the Art+Logic archive · written in 2014. The tools may have moved on; the thinking still holds.

Image of Elephant by Matt Reinbold
See the horror in the elephant's eye? He has a spec due Sunday.Matt Reinbold, http://www.flickr.com/photos/furryscalyman/1830292015/

I’ve had notes sitting around for months for a post on writing software project requirements, but Brett’s piece last Friday on Estimating Software Projects inspired me to pull them out.  Writing and estimating requirements is painful to most everyone involved, highly problematic, totally not hip, and essential to well run projects.  But since it’s probably just as painful to read about writing specs, I’ll keep this bullet-pointy :)

Benefits

Dan Milstein’s No Deadlines For You post, while advocating against estimates and specs, includes good advice for writing them: aggressively (but politely) interrogate the client about the actual underlying problem, rather than their proposed solution.  When possible, help them focus on minimizing the feature set in the first release to reduce the risk and delay before the product is in the hands of the software users.

Brett’s point on estimation applies equally to writing requirements:

Projects where we’ve encountered the most success and happiest clients are those where we’ve maintained a steady rhythm of delivering releases demonstrating continual progress along with a view of the pieces that are left to be built along with [a set of requirements for] the effort still to come. The secret isn’t [writing requirements], it’s [re-appraising requirements], all the time.

Tips

Further reading

Image of elephant by David Woo on Flickr
But this elephant loves reading about specs on her weekend!David Woo, http://www.flickr.com/photos/mckln/2894299407/

Books and papers

Joel Spolsky’s extensive posts

Sample specs and software

keep going

More to explore in Build New.

All Build New resources →
let's talk

Got a problem like this one?

Tell us what's stuck. A real person replies within one business day.

Talk to our team →

Talk to people who know software, not a sales script.

Your first call is with Aja, our VP of Sales. He'll help make sure you're solving the right problem. Here's what you'll cover together:

  1. What you're trying to accomplish

    The business goal first, then the technology.

  2. Possible approaches

    And the tradeoffs of each, in plain language.

  3. Risks you may not have considered

    Technical and business, before they cost you.

  4. Whether AI changes the math

    What's practical, and what's just hype for your project.

  5. Sensible next steps

    Even if the right next step is not us.

book-a-call.ics

Loading the scheduler…

Open the booking page →

Some problems are easier to explain in writing. Send us a few lines about what you're working on, and we'll reply within one business day. Helpful to include:

  1. What the software does, or should do
  2. What's stuck, or what's worrying you
  3. Any deadline or budget you have in mind
note.md

Loading the form…