How To Write Specs

When To Write A Spec

Specifications should be written for any non-trivial project with more than a couple variables. A good rule for this is any project taking longer than 2 days of work by an individual or by a group of 2 or more.

As a guideline, if there is any doubt… write a spec.

Why Bother?

Failing to write a spec is the single biggest unnecessary risk of a software project. Programmers and managers who dive into a project without writing a spec tend to think they’re cool gunslingers, shooting from the hip, they’re not. They’re terribly unproductive.

They write bad code, produce bad designs, whatever… All because they didn’t want to “waste time” doing a little research, analysis and planning.

Specifications accomplish many things including:

  • Helping create alignment about what a given project should do or shouldn’t do
  • Forcing a certain degree of design and planning before dealing with technical complication
  • Compiling all relevant variables in one place
  • Requiring a timeline and consideration of any relevant measurement details or metrics

What to Include

A functional spec describes the entire experience of using a product or service from the user’s perspective. It doesn’t care how things work, it only cares about the end result, the features. It supplies screens, dialogs, and so on.

Here is what a good functional specification includes:

  • Disclaimer
    Describes the scope and purpose of the specification. Says that it ‘may not be comprehensive or complete’ etc..

  • Author
    One, and only one, author who is ultimately responsible for keeping the specification up-to-date. This should never be a team. Individuals should take responsibility and ownership of the things that they specify. If a project is big, split things up.

  • Scenarios
    Include real scenarios of various challenging use cases of the product or service at hand. This will allow you to create contraints for your product and further analyze tradeoffs.

  • Non Goals
    IF there is doubts about including a feature, remove it. We must be minimalists.
    This is where you cull features away that you may see on competitor products, but are ultimately unnecessary.

  • Big Picture
    A top level view of what the project needs to do.

  • Details
    The most important part of the specification. Go into as much detail as possible to describe various features.

  • Unresolved Issues
    Sometimes problems are overly complicated or more information is needed to provide a detailed answer. Leave these here and address them at a later time.
    HOWEVER, by the time programming starts these should all be resolved. It’s ok to adjust decisions at a later point in time, but this is critical as sometimes small changes in one aspect of a project can affect the whole thing.

  • Notes
    Add any specific insights needed to create the right work here. Mental models and additional required reading can be useful.

Keeping Specs Alive

With this workflow its important to keep specifications alive as software gets written and work is created. If it’s not ultimately no one will read the spec and we will be back where we started.

An important tip on this is that when specs are updated, make sure to annotate the changes with dates and revision marks so people can easily spot what’s changed.

Who Writes Specs

Generally the owner of specifications should be technical and have a good understanding of the user problem, desired user experience and technical issues required to generate the desired end result. That said, they don’t need to be great coders or great marketers.

From here, the specification is not the authority. People implementing the specification have full rights to request changes to the spec and seek better answers than those that the spec gives initially.


  • Specs should be simple and concise as possible. Avoid boring language or unnecessary jargon.
  • Trick people into reading your specification by making it human readable and informative. Maybe even funny.

If you read a lot of Dave Barry, you’ll discover that one of the easiest ways to be funny is to be specific when it’s not called for. “Scrappy pugs” are funnier than “dogs.” “Miss Piggy” is funnier than “the user”. Instead of saying “special interests,” say “left-handed avocado farmers.” Instead of saying “People who refuse to clean up after their dogs should be punished,” say that they should be “sent to prisons so lonely that the inmates have to pay spiders for sex.”

  • Write Simply. Break things down into the simplest wording possible. Never use jargon if possible.

  • Include Charts and Screenshots. Even simple sketches can speak a 1000 words when it comes to describing your vision for how something should work.