Comparing writing specifications to writing code
My colleague who manages to pack his entire office into a single box recently made the switch from program management to programming. I teased him, “So what’s it like using an editor without a ‘boldface’ button?” His response was actually rather insightful. “Writing specifications is like writing a novel. Writing code is like writing poetry.” When you’re writing a specification, you need to start by setting the scene so people understand the problem you’re trying to solve. You then explore the world you’ve created, elaborating on the details necessary to convey your intent, considering all the possibilities and addressing each one. When you’re writing code, you are focused on conciseness. Like a poet, you are thrilled when you find a single expression that covers all the nuances you’re trying to convey. You are intent on writing only what is necessary, no more. Beauty is in the small.
I guess this explains why I was never good at long-form writing.