Clay Tech

"clay-works make things real"

translated from clazytech.com

Kuzuryu Says Specs Should Not Be Written Too Early

【Objection ①】

You should write a proper document as early as possible. If you don’t clearly define what you’re building and why early on, decisions during development end up being made haphazardly.

【Objection ②】

You should write documents only when communication with outside parties occurs. As long as things stay internal, notes and whiteboard summaries are enough. Why? Because specs change constantly. If you rewrote the document every time, you’d be rewriting it every day.

【Objection ③】

Don’t write documents except when truly necessary. The cost — the effort — doesn’t match the benefit.

【Yuichiro Kuzuryu’s view】

When I first went to the US, I was struck by how little documentation the people around me wrote. Up to that point my entire career had been in what you might call “development roles at a typical Japanese large corporation,” so even though I found documentation work tedious, I spent my days writing up various papers and getting my boss’s stamp of approval on them. Measured against that standard of mine at the time, I really thought, “none of these guys write any documentation at all.” But I was also fed up with that Japanese document culture, so I threw myself fully into the Silicon Valley way of doing things. And at some point I noticed something.

“They’re prioritizing communication instead of writing documents.”

For example, my boss at the time, J, would say “go read the document on that,” but then wouldn’t actually read it himself. He’d come straight to me and ask. He’d come ask even about things that could be settled with a single yes or no. Even though it was written down. And about 8 times out of 10 it was a curt exchange, but about 2 times out of 10 the conversation would wander off into other topics. The friendly P would come chat at my desk 9 times out of 10 (usually about music or manga), and the knowledgeable E would usually throw in trivia or stories from his time at Apple along with the answer to my question. I see, so this is how it works, I thought. Instead of relying on something as inert as a document, they had a standing openness of “if you don’t understand something, just ask,” and it was baked into them to tackle and solve problems as a team. In an environment like that, documentation was little more than decoration — something put together, if needed, around the time a project was wrapping up. Or when someone was leaving the company.

On the other hand, at a different company I was involved in a project that turned into something of a nightmare: “the person who had originally brought in the project quit, and then the two people who succeeded them also quit.” I don’t know the reasons or circumstances behind why the people in charge quit one after another, but by the time I joined, a junior-level engineer, S, who had been involved from the very beginning, had ended up in something like the responsible party’s position (which makes sense, since he was the only one who knew the full history). I supported that project for a short time, but I simply couldn’t tell what had been achieved and what the remaining issues were. I also couldn’t tell what the original requests had been, or which of them had been declined and which had been taken on. The schedule and the deliverables had both drifted and changed piecemeal, to the point where it wasn’t even clear what commitments were currently in place with the client. What I did next was organize the specifications.

It ended up being completely after the fact, but I untangled the current state and the history — what requirements there had been, what discussions had taken place, and what had been settled on as the landing point. Based on that, I determined the basic specs and the parts to use, and how testing would be carried out. I wrote all of that up, belatedly, and went through the process of getting the client’s approval on it. I cursed, “why wasn’t any of this documented…” To be precise, there was documentation. But it was fragmentary, or it left out the important parts of the history, or it didn’t say how things had ultimately turned out — it was all incomplete in one way or another. The one saving grace was that S, even if he was alone, had stayed on. By talking to S, and by having S and the client talk directly, I was able to untangle the history and the details, and S’s relationship with the client was a good one. In the end, we managed to close out that project.

Now, I’ve touched on two extreme examples, and the premises are quite different — one an in-house product, the other a client project. Even so, in terms of “development,” I don’t think the essence changes at all. The process is exactly the same: there’s some purpose or goal, you build something toward it, you confirm its quality, and then you ship the output.

So how should we think about specifications and documentation? What I recommend is the idea that documentation should always be written with contrast built into it.

The communication-focused approach I described above actually has a major flaw: it depends heavily on individual qualities. Silicon Valley engineers are high caliber in a lot of respects, and that includes their level of communication. I can’t deny that the approach above works, in part, because of that. Which means it may well fail to work depending not just on individual skill but on an organization’s maturity, a team’s management style, and so on. And if you lean too heavily on communication, you can’t avoid problems like “whoever’s loudest wins” or “someone keeps bluffing their way through until they bail before the hole they’ve dug catches up with them.”

That said, producing documentation generally demands a huge amount of time — which is to say, cost. In my third year out of college, I was involved in a project to outsource the development of a certain platform. Compiling the details of what was, in effect, a secret sauce built up over more than a decade of in-house development into a written specification was an extremely grueling task. It also had to be written in English, and as I recall, it ended up taking four people more than two months.

So what I want to propose is always being conscious of contrast — of strong and weak points. You might also call it resolution.

For instance, I was once asked, “for consulting projects, there’s no way to write requirement specs, because often the client’s own requirements aren’t even settled yet. What should I do?” My answer was, “just write the requirement spec with the goal of clarifying the client’s requirements.” The most frightening thing in a project is losing sight of what you’re actually doing — losing sight of the goal. That’s not at the layer of “ship the product,” but the layer of “what are we shipping this product for, and what kind of society are we trying to bring about?” It’s important that this goal be written down explicitly, so that anyone reading it understands it the same way, with no room for interpretation. That’s what documentation is for.

There are also cases where it matters for the specification to say “unknown at this time = TBD.” Rather than thinking “I don’t know, it hasn’t been decided, so I won’t write it,” you should think “write down the fact that it hasn’t been decided yet.” If you think about it that casually, writing a specification shouldn’t feel like such a burden. Finding the right degree of give like this makes it possible to keep documentation going at all times. Try it, and work out your own approach.

Incidentally, the single biggest reason I insist on the importance of documentation is that I don’t trust my own memory all that much.

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/1163/. Translated with LLM assistance and reviewed before publication.