Our industry is all about the communication of ideas. It’s not just about being able to communicate our ideas to a machine – a big part of our job involves the ability to communicate ideas to both technical and non-technical people, as well as translating and solidifying ideas into usable products.
Why is it, then, that so many pieces of technical writing (emails, specifications, design notes, clarifications, books, source code documentation, bug reports, technical manuals and even simple feature requests) end up either way too long and turgid, or so brief as to miss the point entirely?
I’ll start by saying that I’m an expert at neither writing nor programming. I’m not preaching here. This is just about the kind of technical writing I like, the kind I don’t like, and why. Bear in mind that this is also not at all about incoming writing. This is not about what the client is writing to us. It’s about what we write to the client. It’s about what we write to each other.
Effective communication can be the difference between a client relationship that feels like a real alliance versus one that feels like the Cold War. I’ve worked at several companies, experiencing both ends of that spectrum, and I believe that we as engineers have to try and do better than throw our hands up and say “[dealing with the client/communicating features/managing expectations] is simply not my job”. It’s about so much more than that.
I’ll be referring here to technical books specifically, as writing about all the kinds of communication we handle on a daily basis is somewhat outside the scope of this article. Also, a good programming book is meant to take a topic you don’t understand and make you understand it in the shortest possible timeframe. In this way, technical books resemble most of the communication we do on a daily basis.
What I Like
Brevity
Shakespeare once wrote that “brevity is the soul of wit“, which translates roughly to “don’t waste my goddamn time“. The amount of dry, humourless, completely rigid and horribly long prose that gets cranked out by this industry is astounding. Some people seem to write the way their university computer science textbooks were written, forgetting how much they hated reading those things in the first place. Textbooks have loads of hoops to jump through to qualify as textbooks in the first place, and not all of these hoops result in a better experience for the reader. They usually result in a 1000+ page book written in 9pt font that’s pretty much dead on arrival. I’ve seen emails like this. I’ve written emails like this. It’s bad. “Javascript, The Good Parts” is a great example of a book served well by its brevity.
Fun-factor
Continuing the previous point, the thing about textbooks is that they don’t have to get you to read them. You have to read them, because they’re the textbook for your course. You didn’t “hear good things” about them. A book like Scott Meyers’ “Effective C++”, however, isn’t a textbook. It’s a fun book. The examples are interesting, he speaks in a reasonably informal style, and neither of those things detract from the fact that the book is drum-tight, and packed completely full with real programming gems. Pieces of concise information that you feel like a better programmer for having read it, but at the same time really light, and fun.
Simplicity
Einstein once said that you understand a concept if you can explain it to your grandmother. And he was talking about explaining the entire universe, rather than just some CRUD app. A good piece of writing can take a difficult topic and explain it in simple terms, without leaving anything out. The perfect example of a book that does this well is Steven Skiena’s “The Algorithm Design Manual” which not only teaches you about algorithms, but also teaches you to think about algorithms. It’s also personally my favourite book on programming.
What I Don’t Like
Hand-waviness
When I started learning Rails, a lot of the Rails-related articles I read would hand-wave huge amounts of information that would have actually been really helpful as a beginner. This was usually in the service of making the Rails ecosystem look a lot simpler than it actually is. One really difficult thing about technical writing is figuring out what information is actually relevant. If you’re just writing a tutorial, the only relevant pieces of information are the list of commands to get, say, a fresh Ubuntu box running nginx, with perhaps a brief explanation of why we’re running each command. If you’re writing an introduction to a new concept or framework, however, the question of what to leave out becomes a whole lot dicier.
Most of what I initially read on Rails hand-waved enough for me to feel totally lost when my first bundle install failed. I didn’t know what bundler was. I didn’t even know what gems were! Einstein also said “make things as simple as possible, but not simpler“. A lot of what I initially read about about Rails attempted to make it too simple. I actually found learning Objective-C to program for the iPhone easier than learning Rails, mainly because of the things people left out of the Rails tutorials I was reading. There’s a good diagram of everything that’s actually going on when we’re introducing someone new to Rails here.
Complexity
Ah, complexity. In code, we hate it. We try to tame it. But, for some reason, when we talk about said code, we feel no such urge. I love the idea that “a problem well put is half-solved“. There’s something great about that phrase (other than its resonance); it conveys a really important, complex idea in eight syllables. We pay a lot of attention to eliminating redundancy in our code, but I’ve seen many cases where, in written and verbal communication, the important points that we’re making get lost and forgotten in a sea of redundancy and irrelevant technical talk. Bikeshedding is another great example of this. We have a great ability to take a seemingly simple problem and break it down into its complex, fundamental components. It’s part of our job. The problem is that not all of those parts are worth talking about immediately. Learning to decide which ones are is something that takes time and conscious effort.
Arrogance
Engineers are an arrogant bunch. There’s no denying it. The best ones are usually humble, open to criticism, and always willing to learn (Good ol’ Linus Torvalds being both a great counterexample of this and illustration of the point I’m about to make), but many of us feel the temptation to assume that others have the same knowledge as us. We assume that our opinion is correct. All of our stuff is logically correct, so we believe that our opinions about that stuff are also logically correct. This isn’t the case, and it leads to endless hype-cycles, puritanical beliefs in certain ways of doing things, and a general closed-mindedness that is hard to shake. This all stems from the way we think about communication, or more specifically, the way we don’t think about how we’re communicating.
Conclusion
We spend a lot of time communicating, and a lot less time thinking about how we communicate. We’re all about improving our practices and workflow in regards to our engineering, but if you can’t effectively communicate the problems you want to and should be solving, you end up building a perfect, polished product that just isn’t what was required. English should still be our main language, and we should act like it.
About the Author
Software Engineer at Made Tech
Member of the full-stack brat-pack. Enjoys a good blue cheese.
