Kuzuryu Says Silicon Valley Writes Specs Late, Not Early

2022-09-08 original Engineering

【Objection ①】

You should write a proper spec as early as possible. If you don’t clearly define what you’re building and why, right from the start, decisions made during development end up ad hoc.

【Objection ②】

You should write documentation only when communication with external parties is involved. As long as things stay internal, memos or whiteboard summaries are enough. That’s because specs keep changing. If you rewrote the doc every time something changed, you’d end up rewriting it every day.

【Objection ③】

Don’t write documentation unless it’s truly necessary. The cost, meaning the effort involved, doesn’t pay off.

【What I, Kuzuryu, think】

When I first went to America, I was surprised at how little documentation the people around me wrote. Up to that point my entire career had been in what you’d call “development roles at a typical Japanese large corporation,” so even while feeling annoyed by documentation work, I spent my days producing various paperwork and getting my boss’s stamp of approval on it. Judging by my standards at the time, I genuinely thought, “none of these people write any documentation at all.” But I had also grown tired of that Japanese paperwork culture myself, so I threw myself wholesale into the Silicon Valley way of doing things. And at some point I noticed something.

“Instead of writing documentation, everyone here prioritizes communication.”

For example, my boss at the time, J, would say “go read the doc about that,” but even then people wouldn’t actually read it. They’d come ask me directly. They’d come ask even about things that could be settled with a single “yes” or “no.” Even though it was written down. Maybe 8 times out of 10 it was a curt back-and-forth, but about 2 times out of 10 the conversation would drift off into something else entirely. The friendly P would linger and chat with me 9 times out of 10 (usually about music or manga), and the knowledgeable E would usually toss in trivia or stories from his time at Apple on top of answering my question. I see, I thought, so this is how it works. Instead of relying on something inorganic like documentation, they’d internalized a style of always staying open — “if you don’t understand something, just ask” — and tackling and solving problems as a team. In an environment like that, documentation was little more than decoration, something you’d put together only if it turned out to be needed, around the time a project was being wrapped up. Or when someone was leaving the company.

On the other hand, there was a project I got involved with at a certain company that was a nightmare: “the person who had originally brought in the deal quit, and then the two successors after him also quit.” I don’t know the reasons or the circumstances behind why the people in charge kept quitting one after another, but by the time I joined, a junior-level engineer, Mx. S, who had been involved from the very start, had ended up in something like the role of person-in-charge (which made sense, since he was the only one who knew the full history). I supported that project for a short period, but I simply couldn’t tell what had been accomplished 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 drifted and changed so gradually and haphazardly that no one could even say what commitments had actually been made to the client at that point. What I did after that was sort out the spec.

This ended up being completely after the fact, but I untangled the current state and the history: what requirements had come in, what discussions had taken place, and what compromises had been settled on. Based on that, I determined the basic specs and the parts to be used, and how testing would be done. I wrote all of that up, belatedly, and had the client sign off on it. I cursed, “why didn’t anyone leave any documentation…” To be precise, documentation did exist. But it was fragmentary, it left out the important parts of the history, it didn’t say how things had actually ended up — it was inadequate in every way. The one saving grace was that Mx. S, at least, was still there. By talking to Mx. S, and through conversations between Mx. S and the client, I was able to untangle the history and the details, and the relationship between Mx. S and the client was a good one. After that, we somehow managed to close out the project.

Now, I’ve touched on two extreme examples — one an in-house product, the other a client engagement — with quite different premises. But in terms of what “development” fundamentally is, I don’t think anything changes. The process itself is identical: there’s some purpose or goal, you build something toward it, you check its quality, and then you ship the output.

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

The communication-centric approach described above actually has a major flaw. It depends heavily on individual aptitude. Silicon Valley engineers are high-level in many senses, and that includes their level of communication. I can’t deny that the approach above works partly because of that. So it’s entirely possible for this not to work, depending not just on individual skill but on the maturity of the organization, the team’s management style, and so on. And if you lean too heavily on communication, you can’t avoid problems like “whoever talks loudest wins,” or people who pile up empty talk and then bolt before they dig themselves into a hole.

That said, producing documentation tends to demand an enormous amount of time, in other words cost. In my third year out of university, I was involved in a project to outsource development of a certain platform. Compiling into a spec, in detail, something that was effectively a secret sauce built up over more than ten years of in-house development was an extremely grueling task. Since it also had to be written in English, if I recall correctly it ended up taking 4 people more than 2 months.

What I want to propose here is to always stay conscious of contrast — of strong and weak points. You might also call it resolution.

For example, I was once asked, “for consulting engagements, there’s no way to write a requirements spec, since often the client’s own requirements aren’t even settled yet — what should I do?” I answered, “just write the requirements spec with the goal of clarifying the client’s requirements.” The scariest thing in a project is losing sight of what you’re doing and what the goal is. That’s not at the layer of “we’re shipping a product,” but at the layer of “what are we shipping this product to achieve, and what kind of society is it meant to bring about?” It’s crucial that this goal be put into writing, clear to anyone who reads it, with no room for interpretation. That’s what documentation is for.

And depending on the situation, it can be important for the spec to state, “as of now, this is unknown — TBD.” Rather than thinking “I don’t know, it isn’t decided, so I won’t write it down,” you should think “write down the fact that it isn’t decided yet.” If you think about it that lightly, writing a spec stops being much of a burden. By adjusting the level of effort skillfully like this, it becomes possible to always keep documentation on hand. Give it a try, 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 pick up a copy.

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.