Write requirement specs with clear performance numbers and authorization

I don’t need to describe requirement specification templates myself, since various organizations and volunteers already provide all kinds of them. Using whatever fits your own sense or your team’s should be fine. So here I’ll cover a few typical cases of “you can’t get away without this.”

An important role of documentation is to let everyone check it, approve it, and keep it retrievable at any time. There’s nothing wrong with having memos that just summarize what’s in your own head, but that is not a specification. Regardless of the granularity of the information, a specification is something the team has properly reviewed, revised, and authorized. If there’s a client, the specification is whatever has received the client’s review. Proceeding with development using a document that’s just a summary of what’s in someone’s head is dangerous. Get a proper review done first.

At minimum, a requirement specification needs to state “what the purpose is,” “what function is being included,” and “roughly where the line between OK and NG is.” The performance requirement is what determines this “OK/NG judgment.” It’s preferable to write this in numbers as much as possible.

For example, suppose you’re developing an image inspection device that rejects defective products in a factory process. Naturally you’ll need to “capture an image with a camera,” and you may also need to “transfer the image to a computer.” And you’ll need to “detect defective products.” For the camera, you’ll probably need performance requirements like “30fps or higher,” “12M pixels or more,” or “able to save files in JPEG.” You check whether these requirements are met as you proceed with the design. For communication, you’ll have requirements like “use USB3.0” or “complete image transfer within 10ms (TBD).” I’ve put in a TBD here, because the conditions required for image transfer are actually heavily affected by the time taken for image processing, so this isn’t clearly decided at the start of development. The point is to dare to write a number here, and to clearly mark it as TBD.

And the tricky part is “detecting defective products.” What’s the criterion for OK/NG? Which defects must always be detected, and conversely, which defects are handled on a best-effort basis? This is very difficult, but development cannot proceed without deciding it.

“Let’s just build something for now and think about it later” won’t work. Say, for instance, “detecting scratches of 1mm or larger” turns out to be important. From the resolution and the distance to the camera, you can roughly calculate the size of scratch that can be detected. If you’ve already selected a camera from what’s on hand and this specification comes to light afterward, how do you respond? Move the camera closer? Attach a lens? Improve the AI’s accuracy? No — this performance should have been factored in from the very start, at the point of selecting the camera.

Make performance requirements clear, and make sure that everyone whose work is affected by those requirements shares a common understanding of them. Cutting corners here will come back to bite you later.

Specifications get rewritten heavily during development. That’s how it should be, and once development actually starts, it inevitably happens that way. When it does, using a tool that supports history management, and having a system in place where update history is communicated to the team, becomes extremely important. As mentioned above, a specification is something that has been authorized. But there will be times when it has to be changed, and it should be changed. When that happens, maintaining a high level of granularity in sharing with the team becomes an inevitable requirement.

There are plenty of convenient tools these days. Managing it with git is one option, and Google Docs can also be used. For something lighter, Kibela, esa, Qiita Teams, and the like also work. Linking update history to Slack makes communicating to the team easy too. Using tools like this also reduces the load during the review that’s bound to come, which is another advantage.

As shown so far, the level of detail in the content isn’t actually all that important when writing a specification and starting development. What matters is putting the surrounding structure in place — tools, systems, and so on — and writing what needs to be written, and if something can’t be written, writing that it can’t be written. Keeping these basic points in mind is what’s essential.

The content of this post is an excerpt (original text) from the following book. If you’re interested, please pick up a copy.

The Shape of a Happy IoT Startup

The Shape of a Happy IoT Startup

Originally published in Japanese at https://clazytech.com/2022/09/1160/. Translated with LLM assistance and reviewed before publication.