ajpikul.com

posts

Why Senior Engineers Should Write Docs

-- Andrew Pikul

Most engineering organizations document poorly. We have great software ecosystems, but most don't get past first draft. Maybe it's difficult to see business value, but it's there- more than whats obvious. The simplest use cases for documentation is educating users, and therefore reducing support requests. We'll call that "marketing". If you want individual developers to use your product, you need great docs.

Scalable Training

Good, searchable documentation allows engineers to on-board themselves. You can imagine several ways to get information- from the highly searchable QA format of StackOverflow to the lecture-format of YouTube- and the best APIs litter the internet with docs. A video might not be easy to produce, but markdown style documentation- both references and tutorials- and forum style question-response can be a) very accessible, b) cheap to produce, and c) extraordinary useful to reduce mistakes and trainings.

Permanent Assets

Embedded and hardware engineering has the most severe documentation requirements since they have diverse supply lines and esoteric components. Engineers with massive working knowledge of specific systems find themselves with job security being the living reference for a system. Using accounting terms, systems knowledge is part of "Workforce In-Place" or "Assembled Workforce", an intangible asset describing a trained workforce. You often see its value when a company is "acquihired". Although there are many specific sources of this value, it includes working systems knowledge. Proper documentation represents a transfer of the "Workforce In-Place" (WiP) asset to "Intellectual Property" (IP), which is easier to maintain as it doesn't degrade (skill loss and turnover). In general, IP is more easily measured and transferred than WiP.

Formal Policy

Proper documentation also represents encoding of policy. It is simply a way to keep processes organized and consistent. This is an extremely intuitive benefit of documentation, and like the section above, codifies the manager's experience. This is important as a large system may become fragmented and untenable when it's being contributed to by a rotating workforce. Different architectures, different patterns, different approaches all mean more more hacking and bodging when things aren't constructed cohesively.

Dogfooding

You must dogfood documentation. Your engineers can read and make modifications to documentation. When you have a large working knowledge of a system, it's easy to correct technical issues, but its difficult to understand what is good and bad teaching (without feedback) because you've lost the perspective of a beginner. The best user to decide how to make things easier for beginners is the beginner themselves, so you must dogfood the documentation and encourage those engineers to submit changes. A fragmented undocumented system is compounding technical debt, and it can be deadly.

Customer Facing

The impact of consumer facing documentation is so obvious it barely made this article accept the list wouldn't be complete without it. Two strong benefits are a) marketing: educating your consumer on how to use your product so that they can integrate with it and b) preventing support costs.

That's it for now. I love writing about why we should write more! The other title for this post was "Documentation for Documenting". If you made it down here, ping me on twitter and let me know what you thought! All feedback, even the harshest, is appreciated.