Two Underused Arguments for Writing Documentation

Published on April 30, 2023 (↻ June 23, 2023), filed under Web Development and Engineering Management (RSS feed for all categories).

Writing documentation is important, to explain and share knowledge about the purpose and workings of a subject, and to enable collaboration and continuity. For this reason, writing documentation is a useful skill and habit to acquire and cultivate.

When we talk about documentation, however, I believe there to be two reasons for it, and benefits, that don’t get much or enough attention:

1. Validating Thinking

Documenting allows us to validate our thinking. (This is to be read as being open to invalidation.) As with transparency in general, the act of sharing information enables scrutiny, which allows to learn about oversight or error.

This is better than keeping our knowledge under wraps, undocumented, not exposed to critical view.

2. Allowing to Scale

If relating to instructions, documenting enables others to do the same work, which means that we may not need to do it ourselves anymore. This isn’t a new point by itself—what’s less obvious though, and not always communicated well, is the scaling part. If something isn’t documented, or is only documented poorly, it’s hard to scale.

This is better than keeping our knowledge under wraps, creating bottlenecks or bus factors. (In our field, this is particularly important for senior engineers. It also shows, then, why making oneself “indispensable” by withholding information is not a good call, and may backfire.)

❧ These are two arguments for, and incentives of, writing documentation that we make less use of than we may want to make. When kept in mind, they may help those asking for documentation build stronger cases for it, and those asked to provide documentation with professional growth.

Please share your thoughts and observations, perhaps as a response to the toot for this post.

About Me

I’m Jens, and I’m an engineering lead and author. I’ve worked as a technical lead for companies like Google and as an engineering manager for companies like Miro, I’m close to W3C and WHATWG, and I write and review books for O’Reilly and Frontend Dogma.

With my current move to Spain, I’m open to a new remote frontend leadership position. Feel free to review and refer my CV or LinkedIn profile.

I love trying things, not only in web development, but also in other areas like philosophy. Here on meiert.com I share some of my views and experiences.