Software Engineering in Large Organizations: Requirements

Figuring out what the heck it is you are going to do is the most important part of any project, isn’t it? It’s the case whether you are fixing a toilet (which I outsource) or building the next version of a software package. As a team lead I always wanted everyone on the team to be able to describe in couple of sentences what it is that we are trying to achieve, and their role in it.

Requirements are invented things. This everyone knows, but at small companies people tend to forget to write them down, and at big companies people tend to forget that they can be changed. Either way, it’s important to keep in mind that requirements must be clearly articulated otherwise they will surely not be met. In other words, we need to write down requirements so that we will be able to determine whether we have met them. Once they’re written down, requirements documents can start to seem like stone tablets. Requirements do not exist for their own sake, but to realize a larger vision. If we can’t explain why a requirement is a requirement, then something has gone wrong. It’s common to question requirements later on in a project – perhaps they are too hard to implement. That’s okay to some extent, but in many cases people are just a bit too sloppy about thinking about (and writing down) requirements at the start of a project.

Where do requirements come from? We already said they are invented, but how do we invent them? Big companies draw from many sources:

  • User surveys
  • Instrumentation
  • Senior management
  • Customer advisory boards
  • Partner feedback

The “Building Windows 8” blog is a wonderful public example of such artifacts. The B8 blog gives a true sense of how requirements are developed for a “big league” project. Basically the idea is to be like a five year-old: keep asking why questions until you get to axioms.

Also notable is the Russian doll-like nesting of requirements inside of requirements. Even a much smaller project like Solver Foundation cannot simply have one requirement document. Requirements are typically written down in increasingly narrow form: from a vision document to scenarios to themes to features to specifications. A specification, or “spec”, is the fundamental unit of requirements at a larger software shop. It describes a unit of work specified by a single PM, implemented by a single developer, and tested by a single tester during a single product release (or milestone).

Specs should:

  • provide justification for the feature
  • state goals
  • state non-goals
  • define user scenarios
  • imply a self-contained unit of work
  • specify integration points
  • describe performance goals
  • be written for the engineering team
  • be self-contained

They should not:

  • describe how a feature is built
  • be a list of APIs
  • be written in “business speak”
  • be written for management

Sad to say, it is often the case that a spec ends up beginning with an amateurish mishmash of MBA gobbledygook and ending with a hastily cut-and-pasted set of API signatures, with comments from ten different people in the margins. Few things are less useful and more depressing than a spec of this kind. Be clear, don’t try to impress, and justify your reasoning. Write for someone who is smart but is not intimately familiar with your product and team history. After all, those are the kinds of people who will be using the thing you’re trying to build.



Author: natebrix

Follow me on twitter at @natebrix.

Leave a Reply

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

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

Twitter picture

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

Facebook photo

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

Connecting to %s

%d bloggers like this: