On technical writing

I am convinced that technical writing for an engineer that does business software (products for clients), is an essential skill.

I am specifically referring to design documents, the artifacts that capture the design for the software you are about to write.

I will talk more about the format and the process in later posts, for now I just wanted to capture the imperative behind design documents.

Toolbox: Design document is not the only tool at your disposal. Over the years one does develop a toolbox of techniques that helps with the design process. Design document is merely one of them. Design documents are not “documentation” in a sense that many engineers despise. Design documents are not the implementation manuals or Business Requirement Documents (BRDs). Design documents are a part of the engineering process, they are the engineer’s job. You might find out that in some cases this design part might be even more difficult than the implementation itself.

Nature of engineering work: As engineers, we work in mental models. A lot of our work is understanding the real world concepts, and translating them into software. It is the work of conceptualizing, of clarifying and capturing the context, of simplifying and organizing, of establishing connections and thinking through interactions. This sort of software is a social enterprise, where one needs to talk to design, product, and other engineers.

Writing, especially structured technical writing, is a powerful tool. It not only captures the above, but actually helps us to do the work of defining the problem and designing the solution for it.

I would go as far as to suggest that if one cannot clearly express what is being built, why, and how it works, and what pieces it consists of and how they interact, and what are the drivers behind the design decisions, it means that they do not understand it well, and as a result, the implementation will be flawed or incomprehensible to others that follow (or even yourself, just a few months down the road).¹

It is a skill one can learn. There is no flash of inspiration needed to produce thrilling and ingenious page-turners. I am after the ability to express thoughts in an organized manner and explore the problem and solution spaces to come up with the design that works and then communicate it to others.

Agile into the corner: I noticed that oftentimes in the name of agile we refuse to do the upfront thinking and planning altogether. Understandably, it is hard early on, and there are a lot of ambiguities and unknowns. With agile’s quick incremental steps, just enough building to get feedback, there is always a risk of iterating yourself into a corner. Agile should not prevent us from some amount of thinking and planning upfront. The right balance of learning and adjusting vs. upfront design will come from experience. At the end of the day, it boils down to the old adage “think before you do” which will let you correct mistakes during the design phase, while it is still cheap to do so.

Plans vs planning: Another maxim to consider is, “planning is everything but plans are nothing.” Your design document will help you create a framework for decision making when the designs and plans inevitably change. The work you have done upfront will allow you to adapt and evolve better.

Organizational scalability: Finally, consider your engineering culture and organizational memory. It is a scalability game - as the org grows, this is how you ensure that the decisions and thoughts behind them endure. You avoid revisiting them, you create the guardrails and the foundation. If you subscribe to the shorthand that “culture is how we do things around here,” then your design document process models how the org thinks and approaches design and building of the software. Design documents amplify the impact of senior engineers, create ambient awareness, and promote consistency.

With this preamble out of the way, I will write about my experience with various formats and processes.

1. this is why the old engineering adage, “naming is hard,” belies this true nature of engineering work—of course you cannot name things well if you do not understand them ↩