Here is an article which describes this topic, based on Joel Spolsky's 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".

✦

Introduction

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!