ajpikul.com

posts

Why Senior Engineers Should Write Docs

-- Andrew Pikul

Why do so many engineering organizations do documentation so poorly? We have great software ecosystems, but we rarely publish a first draft. Maybe its difficult to see business value, but its there! And more than whats obvious. The simplest use cases for documentation is educating users, and therefore reducing support requests. We'll call that "marketing", but there is so much more, even if your internal tech isn't consumer-facing. Sufficient to say, if you want individual developers to use your product, you have to document it well. Protip: Experienced engineers can write documentation before they write code.

Scalable Training

Good, searchable documentation allows engineers to on-board themselves. Strong readers and self-taught individuals do this the most powerfully. Technical people rely on several mediums to get information- from the highly searchable QA format of StackOverflow to the lecture-format of YouTube, the best frameworks populate the internet with their documentation. The amount of time investment in a video probably isn't worth the exposure (it depends). 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 since they're the living reference for a system. 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. Github is fantastic source of collaboration, I highly recommend making pull requests on documentation. 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.