Write specs at the right level before development starts
There’s no need for me to describe the requirements specification template itself, since various organizations and volunteers already provide many versions of it. Use whatever matches your own sense of things, or your team’s. Instead, I’ll cover a few typical pitfalls here: things you can’t afford to skip.
An important role of documentation is that everyone checks it, it gets approved, and it can be pulled out at any time. There’s naturally room for notes that just summarize what’s in your own head, but that isn’t 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, it’s something that has received the client’s review and approval. Proceeding with development on a document that’s just a summary of what’s in someone’s head is dangerous. Make sure to get a proper review done first.
<Performance requirements aren’t clear>
A requirements specification needs to state, at minimum, what the purpose is, what function is being included, and roughly how OK/NG will be judged. It’s the performance requirements that determine this “OK/NG judgment.” These should be written in numbers as much as possible.
For example, suppose you’re developing an image inspection device that rejects defective products on a factory line. Obviously you’ll need to capture an image with a camera, and you may also need to transfer the image to a computer. You’ll also need to detect defective products. For the camera, you’d probably need performance requirements such as “30fps or higher,” “12M pixels or more,” or “able to save files in JPEG.” In the course of the design process, you check whether these requirements are being met. For communication, you’d have requirements like “use USB3.0” or “complete image transfer within 10ms (TBD).” I put a TBD in there deliberately, because the conditions required for image transfer are, in practice, heavily affected by how long image processing takes, so this isn’t clearly decided at the start of development. The point is to write down a number here anyway, and to explicitly flag it as TBD.
The tricky part is detecting defective products. What’s the criterion for OK/NG? Which defects must always be detected, and which can be treated on a best-effort basis? This is extremely difficult to pin down, but development can’t proceed until it’s decided.
“Let’s just build something for now and think about it later” won’t work, for a simple reason. Suppose, for instance, that detecting scratches of 1mm or larger turns out to be important. The size of a detectable scratch can be roughly calculated from the resolution and the distance to the camera. If you’ve already picked a camera off the shelf and this requirement surfaces afterward, what do you do? Move the camera closer? Attach a lens? Improve the AI’s accuracy? No: the conclusion will inevitably be that this performance requirement should have been factored in from the very start, back when the camera was being selected.
Make performance requirements explicit, and make sure everyone affected by them shares a common understanding. Skip this and it will come back to bite you later.
Specifications get rewritten constantly during development. That’s how it should be, and once development actually starts, it inevitably happens. At that point, it’s extremely important to use a tool that supports version history management, and to have a system in place so the team is notified of updates. As mentioned above, a specification is something that’s been authorized. But there will be times when it needs to change, and it should change. When that happens, maintaining a high level of shared visibility across the team becomes unavoidable.
There are plenty of convenient tools these days. Managing things with git is one option, and Google Docs also works. For something lighter, tools like Kibela, esa, or Qiita Teams work too. Connect update history to Slack, and communicating with the team becomes easy. Using tools like this also reduces the load during the review that’s bound to come later, which is another benefit.
As shown so far, when it comes to writing a specification and starting development, the actual level of detail in the content isn’t really all that important. What matters is putting the surrounding structure in place — tools and systems — and writing down what needs to be written. If something can’t be written yet, write down that it can’t be written yet. Nailing down these basic points is what matters.
The content of this post is an excerpt (original text) from the following book. If you’re interested, please get 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.