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.

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.