you're reading...

Why write software specifications?

“Failing to write a spec is the single biggest unnecessary risk you take in a software project”

Joel Spolsky

In certain cases, there is no alternative to writing specifications about the software to be created.  When contracting out software development, one party obviously has to describe in some details the requirements of a project or system that the other party will build.  When proposing a standard, a detailed description of that standard is needed before anyone can start reviewing and considering it.

Most software teams, however, will not be required by external forces to write any specifications at all for the software they are working on.  These teams must decide for themselves whether they need specifications, and if so, why.  Below are the three most convincing reasons I have experienced which have convinced me of the value of writing specs – whether they be requirements, functional, design, or test specifications.

Writing helps clarify the thinking

Writing down thoughts, whether on paper, on a whiteboard, or in a Word document improves tremendously the thought process.  Writing allows us to record significantly more ideas and details than we can comfortably handle by memory alone.  It allows us to review these ideas and their derivatives and focus on them one at a time.  It allows us to spot missing or overwhelming details.  It allows us to represent complex ideas with formal notation, diagrams, tables, or lists,  and explore them in a structured way to an arbitrary degree of detail.   It allows us to record and thus remember any new questions and later attack each of them until they are all resolved.

More importantly, writing forces us to structure all this information and organize it into a logical form, which often helps us find properties we may not have seen before.  Personally, on a number of occasions I have found solutions to problems when at the end of my investigation, convinced that there is no solution, I sat to write a detailed email explaining why I could not solve the problem, only to find I was making incorrect assumptions.

Writing enables communicating ideas to others

Creating software is a team sport in which even simple features may have multiple interested parties – such as other developers, testers, customers, partners, the marketing team, or the legal department to name a few.  Reviewing a set of requirements or a feature design in person with more than a few people has significant management overhead (scheduling meetings with people, compiling and distributing notes from the meetings, etc.).  Emailing a link to a document or an attachment, on the other hand, is typically quite reasonable.

Communicating ideas to others allows us to get feedback and improve them.  Fear of receiving feedback could be an important reason why so many capable engineers and managers shy away from taking on the task to write a spec, however it should be considered the primary reason why writing a spec should be undertaken in the first place.

Writing creates a trail of considered approaches and decisions

The final design of a particular feature is often a compromise of meeting partially a number of contradictory requirements and resource limitations.  Once implemented, the source code is unlikely to tell the story of all the decisions that were made, or all the requirements that had to be satisfied – it just is the one implementation that was considered the best possible at the time.  Having a detailed trail of considered approaches and decision justifications will save a lot of work for future engineers who will need to get up to speed with the code and build on top of it.

Those reasons pretty much sum it up – writing helps clarify the thinking, enables communication of ideas, and leaves a trail.  If this summary is not convincing, try an experiment – next time you have to write a feature that is not spec-ed, challenge yourself to write a specification for that feature first.  You may end up with a big surprise, such as realizing how much more work may be needed for that feature – possibly by as much as an order of magnitude more than the current estimates.

Relevant additional information



  1. Pingback: The essential tools for writing readable specs | Life in software - February 9, 2014

  2. Pingback: What is a software design specification? | Life in software - February 9, 2014

Leave a Reply

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 )

Twitter picture

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

Facebook photo

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

Google+ photo

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

Connecting to %s

%d bloggers like this: