Reading and writing about work

I've recently had the opportunity to refresh a knowledge base at work. As I sit down to discover what I can learn, and what I can contribute, I'm reflecting on the value of reading and writing about the systems we build. As we enter an era where we're writing much less software by hand, I suspect that the practice of reading and writing about our systems, including the problems we're trying to solve, and how we're solving them, is likely waning as well.

In my career, I've worked on three teams that cared deeply about optimizing processes for knowledge sharing. I've worked on many others that valued this practice to a lesser degree. The teams that valued knowledge sharing built norms around the practice of reading and writing content by engineers and domain experts. Each was different in terms of scale and culture; one, a ~100-person medical device startup. The second, a big-tech (FAANG) company, where I subcontracted for several months. The third was within a team I led; we spent several years building custom knowledge base software within a 15-person software agency.

The factors driving the perceived value of knowledge sharing differed at each company. The medical device startup's work product was highly regulated; producing and maintaining standardized documentation was protocol. However, its leadership also leaned heavily into contributing to an internal Q&A board and protected dedicated time for engineers to spend asking and answering questions. Managers and leads encouraged new engineers to orient themselves through self-directed exploration of the Q&A system and other documentation. The big tech company optimized its knowledge management for a globally-distributed team. The knowledge base here helped developers easily identify subject matter experts and navigate massive codebases and complex infrastructure with autonomy. My own team, a small cohort within an agency, captured knowledge as a means to optimize onboarding staff to time-sensitive client work, which was often championed by one or two individuals. We also shared specialized knowledge with each other in areas like web accessibility and machine learning.

Working within each of these teams taught me the value and challenges of reading and writing about work. Practices of knowledge sharing within groups emerge from the skills, tastes, and discipline of the particular group, as well as historical context and other external conditions.

What did each of these contexts, where "writing docs" was the norm, have in common? Reflecting, two things come to mind: improved autonomy and conscious interdependence (or, perhaps, community?). When there is a practice and expectation that knowledge about design and decision-making will be shared, as a new engineer, I know I can orient myself by reading and asking questions. As a contributor, effective writing and question-answering force me to think clearly about my work. As a lead, I know that the team will maintain the context it needs to sustain expertise, which enables the potential for more thoughtful decisions and more empowered decision-making.

Writing takes patience. It's not easy to write well. It's all the more difficult to write well about complex, evolving systems for an audience whose questions and curiosity you must broadly anticipate. It's also not always pleasant to read docs -- many knowledge bases are woefully incomplete, fragmented, and littered with stale information. That said, I believe it's more important than ever for engineers -- humans -- to read and write about what we build. The process of human learning, reading, and writing is slow, by the standards of our typical work culture; this slowness, and the moderate pain associated with the maintenance of knowledge-sharing systems, is crucial to our collective wellbeing.

I hope we see more teams invest time in thoughtful human learning, including reading and writing. I believe it is perennially valuable to turn our attention to one thing at a time, for extended periods. It's crucial that we listen to and read the thoughts and decision-thinking of those in our respective communities, and that we take time to thoughtfully share our own. The practice of thoughtful knowledge sharing builds intuition, empathy, and reasonable decision-making skills, and we must not sacrifice these skills for the sake of apparent productivity.