SoftwareEngineering Writing Documentation Technology

Why Don’t Engineers Write?

8 Feb 2019

I trust that every Engineer, in every one of their jobs, has had this moment: “Why didn’t anyone write down why this…” And there are a lot of ways that sentence can end. I’m focused on the first part. Engineers actually don’t like to write things down.

I was having a conversation with a CTO about documentation. He readily admitted that yea, there is less than he’d like. And then he admitted something that surprised me: people are bad writers, they just don’t do it well. If you don’t do something well, you avoid it.

In a very real way, programming is writing. You have two audiences, one is the compiler, and the second audience is the other humans that are going to have to deal with your creation. In all our proper education we focus on writing for the compiler. Yes, there is now a focus on “clean code”, style, and making your code expressive. But its always secondary—because if your code doesn’t run, no one cares if they can read it.

We’ve been given a stereotype of the nerdy computer programmer, unsociable, frustrated, incapable of interacting with anything except a computer. They live in basements, in the dark, banging on keyboards, working alone, creating amazingly important things. The solo hero. Its a false stereotype. It is harmful for others to believe this about us. It is harmful for us to believe this is the highest ideal for ourselves: “Everyone get out of my way, you cannot comprehend by power (and I certainly cannot communicate it to you)!”

I honestly believe if we Engineers were better writers our code quality would improve. Few engineers focus on improving their writing (Hey, I’m trying here)!

I’ve been thinking about the state of the industry as a whole. Why have we been unable thus far to mimic other construction and engineering industries; creating interoperable and re-usable building blocks. After all, that is how our computers themselves get built. Software vendors and platforms are nothing at all like going to a lumber yard, RadioShack, or Home Depot, where you can show up with specs and walk out with what you need knowing it will work.

Maybe, if programming is more similar to writing than we are willing to admit—the industry will never get there. After all, what interoperable and re-usable building blocks do writers have? None that I can think of. Maybe, just maybe, that is what distinguishes an Engineer from a programmer. Their ability to communicate in writing.

Read more: Why Don’t Engineers Write?