Two Underused Arguments for Writing Documentation

Post from April 30, 2023, filed under Web Development and Everything Else (feed).

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 Google, I’m close to W3C and WHATWG, and I write and review books for O’Reilly. I love trying things, sometimes including philosophy, art, and adventure. Here on meiert.com I share some of my views and experiences.

If you have a question or suggestion about what I write, please leave a comment (if available) or a message. Thank you!