How to Write Great Functional Specifications, According to Joel Spolsky

Joel Spolsky is a well-known software developer and author, and his book “Joel on Software: And on Diverse and Occasionally Related Matters That Will Prove of Interest to Software Developers, Designers, and Managers, and to Those Who, Whether by Good Fortune or Ill Luck, Work with Them in Some Capacity” is a must-read for anyone working in the software industry. Among other things, the book discusses the importance of writing specifications in the software development process, which is very important knowledge for everyone working in the Software Development industry. I sum up the most crucial aspects of the book and hopefully will encourage you to read it.

Why is writing a specification important?

Omitting a specification is the single most significant unjustified risk associated with the entire project. It’s essential to write a specification not just for the benefit of the programmers but also to design future programs. A specification helps save communication time, and without one, it is difficult to prepare any schedule.

What is a specification?

When you design a product, it’s essential to consider the expectations and capabilities of its future users. In the case of software, the user needs to know which windows they have access to, what they can do in them, and what the effect of their actions will be. It doesn’t make sense to argue about the programming language best suits the intended product before deciding what the program will do.

There are two types of specifications: functional and technical. The functional specification describes how the product will work (as a whole) from the user’s perspective. The technical specification, on the other hand, describes the internal implementation of the program.

Elements of a functional specification include:

• A disclaimer about the incompleteness of the document.
• An author/authors responsible for the specification.
• Scenarios or user stories that describe how the product will be used.
• Nongoals, or what the product will not do.
• An overview or brief description of the product.
• Details forming the core of the document.
• Potential issues or things that are not yet known about how the product will work (often referred to as TODOs).
• Side notes and remarks addressed to interested parties such as graphic designers, programmers, and designers.

Who should write the specification?

In the past, in big software companies like Microsoft, the responsibility of writing a specification was on one designated individual. This person was named the “master programmer,” and was responsible for writing the entire code and utilising the help of a team of junior programmers as “code slaves.” But this approach did not work well as it was discovered that instead of worrying about testing every feature, this person should focus on developing prototypes of those features and drawing a framework for the planned solutions. That’s how the role “program manager” was formed to replace the old-fashioned “master programmer”. As stated by Jabe Blumenthal, who invented the name for the new role, the program manager would own the design and the spec for products, as well as be responsible for coordinating marketing activities, documenting, testing, preparing different language versions, and carrying out all tasks that should not distract other developers from their proper tasks.

However, it’s important to note that the skills necessary to be a good program manager are very rarely the skills for being a good programmer. Also, rewarding good programmers with promotion has the opposite effect, and employees tend to be promoted to positions beyond their level of competence. Even the best employees of the marketing department rarely have sufficient knowledge in the field of new technologies, so it’s important that this role is filled by someone that has the relevant skills.

Tips for writing specifications

• Be funny and make reading your specification enjoyable.
• Consider the specification writing process as a form of planning.
• Use simple language as much as possible.
• Review and read your documents repeatedly. As Ernest Hemingway said, “The first draft of everything is shit.” Writing, then editing and updating, is an integral part of the process.
• Avoid using templates, as each project is different, and you don’t want to fall into monotony. Just as all books don’t look the same, your specifications shouldn’t either.

A functional specification example

This illustrative spec fragment applies WAYF’s discovery practice to scheduled publishing in a content platform. It is a worked example, with a scenario, behaviour, acceptance criteria, nongoals and open issues; the requirements below are proposed for this example rather than taken from a client project.

Scenario. An editor updates the careers page on Friday afternoon. The new copy should appear on Monday morning. They set a publish date, close the browser, and do nothing else.

Details. The publish control offers two options: publish now, and publish at a chosen date and time. Choosing a date moves the document into a Scheduled state, which appears in the document list with the date beside it. A scheduled document stays editable, and editing it leaves the schedule in place. Editors choose times in their own timezone, shown next to the field; the stored value is UTC.

At the scheduled time. The system captures the latest saved revision and rebuilds the affected pages from it. Only a successful rebuild makes that revision public and moves the document to Published. If the rebuild fails, the existing public pages remain unchanged, the document stays Scheduled with a visible failure status, the editor who set the schedule receives an email, and the failure is recorded in the publishing log.

Nongoals. Scheduled unpublishing, recurring schedules, and a queue showing everything scheduled across the site are out of scope for this release. The queue is tracked as separate work.

Open issues. Who receives the email when the editor who set the schedule has left the organisation. What happens when a second editor replaces a pending schedule, and whether the first editor is told.

Most of the value sits in the constraints. A scheduled document stays editable, the failure path has a defined outcome, and the nongoals close off questions a developer would otherwise carry into the build. A fragment this size can be reviewed in a single meeting, and each line in it is specific enough to argue with.

Reviewing the specification with stakeholders

A specification is reviewed by the people affected by what it describes. On a content platform that is usually the product owner, one or two editors who will use the feature every day, the engineer who will build it, and whoever holds the budget. Editors catch what does not match the working day, and engineers catch what is undefined.

A review comment earns its place by pointing at a sentence and naming what it leaves open. Against the line about a scheduled document staying editable, a reviewer could ask: “If an editor saves while the scheduled rebuild is running, does that edit become public or stay in draft?” The answer changes what gets built. Before approval, reviewers should walk through the scenario and its failure path against the acceptance criteria.

Sign-off covers the scenarios, acceptance criteria and nongoals. Agreeing them fixes what the software will do, how it will be checked and what is outside this release. Open issues carry an owner and a date by which each has to be answered. An issue that affects scope, cost or acceptance blocks sign-off on the affected work until it is resolved. Independent work can proceed within its agreed scope, with the remaining questions visible to both sides.

Summary

In conclusion, Joel Spolsky’s book “Joel on Software” is a must-read for anyone working in the software industry. It emphasises the importance of writing specifications in the software development process and provides several chapters on how to write highly detailed specs and schedules before starting a project. Even though the technologies employed might be old, the subjects of hiring, rewards, wireframing, and engineering were thought-provoking and still relevant. The book is suggested despite the author’s ubiquitous and self-aggrandizing Microsoft citations. Have a nice read!

FAQ

1. Why is writing a functional specification important?

   Omitting a specification is the single most significant unjustified risk associated with an entire project. A specification saves communication time for the whole team, and without one it is difficult to prepare any schedule.

2. What is the difference between a functional and a technical specification?

   A functional specification describes how the product will work, as a whole, from the user's perspective: which windows or screens they have access to, what they can do in them, and what the effect of their actions will be. A technical specification instead describes the internal implementation of the program.

3. What should a functional specification include?

   A disclaimer about the document's incompleteness, the author or authors responsible for it, scenarios or user stories describing how the product will be used, nongoals covering what the product will not do, an overview of the product, the core details, open issues or TODOs, and side notes addressed to designers, programmers, and other interested parties.

4. Who should write the functional specification?

   The role, now typically called a program manager, owns the design and the spec for a product and coordinates marketing, documentation, testing, and localisation, so that developers are not distracted from their own work. The skills that make someone a good programmer are rarely the skills that make them a good program manager, so the role needs a person with the relevant strengths rather than a promoted developer.

5. What are Joel Spolsky's tips for writing a good spec?

   Make the specification enjoyable to read, treat writing it as a form of planning, use simple language, and review and edit it repeatedly rather than treating the first draft as final. Avoid using a fixed template, since every project is different and a template pushes specs toward monotony.

6. What does a functional specification example look like?

   One section of a specification covers a scenario, the details of how the feature behaves, the nongoals, and the issues still open. A scheduled publishing example names the two publish options, the Scheduled state and whether a document stays editable in it, what happens when the scheduled rebuild fails, and which related features are out of scope for the release.

7. How do you review a functional specification with stakeholders?

   The reviewers are the people affected by what the document describes: the product owner, editors who will use the feature daily, the engineer who will build it, and whoever holds the budget. A useful comment points at a sentence and names what it leaves open. Sign-off covers scenarios, acceptance criteria and nongoals. Open issues have owners and dates; anything affecting scope, cost or acceptance must be resolved before that work is signed off.