Two Underused Arguments for Writing Documentation
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.
I’m Jens, and I’m an engineering lead and author. I’ve worked as a technical lead for companies like Google, I’m close to W3C and WHATWG, and I write and review books for O’Reilly and Frontend Dogma. 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.
If you have a question or suggestion about what I write, please leave a comment (if available) or a message. Thank you!
Maybe of interest to you, too:
- Next: CSS Naked Day and the Missing Wikipedia Page
- Previous: On Ageism
- More under Web Development and Engineering Management, or from 2023
- Most popular posts
Looking for a way to comment? Comments have been disabled, unfortunately.
Get a good look at web development? Try WebGlossary.info—and The Web Development Glossary 3K (2023). With explanations and definitions for thousands of terms of web development, web design, and related fields, building on Wikipedia as well as MDN Web Docs. Available at Apple Books, Kobo, Google Play Books, and Leanpub.