Simple secret to writing world class documentation

Aug 18, 2024

There are usually three aspects of good documentation: completeness, accuracy and clarity.
Software Engineering at Google, Tom Manshreck [Chapter 10]

The problem

Frustration with documentation usually falls into four tiers

Tier 0: Where is the documentation?
There is no documentation available, therefore you must rely on inspecting code or consulting with someone to figure things out.
Tier 1: The Cheat Sheet
Sparse, incomplete documentation, primarily written by the engineer for themselves.
Tier 2: Rust
Documents are present, however they have not been properly maintained or updated. Dangerous, may be misleading, and cause a loss of productivity.
Tier 3: The 500-page monolith
Documentation is all there but it is unorganized, difficult to parse and understand.

Why you should strive for good documentation

This is the first line of defense. The document review is where the team gets involved and provides feedback. This is the best opportunity for you get your design vetted. The better your document is, the more your team will comprehend it and help you identify flaws.
Your opportunity to truly showcase your work and demonstrate your clarity of thought. Good documentation demonstrates that you are a diligent engineer who pays attention to detail and can be counted on to own the block. It is an excellent indicator of the quality of your code.
There is a self-reflective aspect to writing documentation. This is where you put pen to paper and distill your ideas into meaningful paragraphs. The process of writing has helped me weed out issues and reevaluate my decisions.
Lastly, CYA — Fabricating a chip is expensive. You must maintain proper bookkeeping over the course of your deliverables and be able to explain why particular design or verification decisions were made. Were they reviewed? Who signed off on it? In short, a good document offers you insurance of sorts.

Potential solutions

Tiers 0, 1 & 2

The good news is that tiers 0, 1 and 2 can be easily solved by putting a process in place. The manager or project lead can then ensure that good documentation practices are upheld. Two eventualities that need to be addressed are:

Engineers who believe their time is better spent doing other things should be nudged and reminded that the task is only complete if the documentation is completed.
For engineers that are motivated to write great documentation but lack the time, the manager should set aside time and allow them to accomplish the work to a high standard.

Tier 3

Designs these days are complex, and specifications will be lengthy. There is no way around it, however here are some things to consider with regard to document organization and style of writing.

I. Know your audience

In semiconductor engineering, you can safely assume that people of at least three different nationalities will read your documentation. I’m a South Asian, and while English is my first language, my proficiency is a distant second to a native English speaker from the West. Add to that, people from different countries come with their own special flavor of english, not only in terms of accent but also in how we phrase our sentences to communicate technical ideas.

So, one of the secrets to good documentation in the hardware industry is, know your audience. Considering this one fact alone will bring you much appreciation from your team.

II. Understand how your document is used

Understanding what YOU look for in a document, will in turn help you become a better writer. I find myself using documents in two modes:

As a tutorial:

When I’m assigned a block of work, I need to deeply understand how it works, so that I can accomplish my obligations.
I rely on the document to be complete, with clear diagrams and necessary hyperlinks to other resources which I might need.

As a reference:

In the course of my work, I often revisit sections of the specification to clarify my understanding of a feature, or quickly extract information.
For this, I appreciate if key information is represented as a table, a flow chart, or pseudo-code instead of a wall of text.

III. Refactoring

Documentation, like code, needs to be refactored to meet production quality standards.
If you observe that numerous coworkers are asking similar questions, it is likely that something in the document needs to be explained differently.
After writing a few paragraphs, I assess my writing in terms of effective bandwidth. The thing about writers I admire (and quite frankly, envy) such as Noahpinion and Wes Kao, is that they have a large vocabulary to dip into, which I lack. They can effectively explain ideas in a single sentence because of the language they utilize and how creatively they construct their sentences. I can't achieve what they do with just words, so I make significant use of diagrams and visualizations. As they say, a picture is worth a thousand words.

That’s it for this episode, stay tuned for the next one.

Opening Picture: A scene from Death Note