Setting the stage
As Peter Naur introduces in "Programming as theory building," the programming endeavor, and thus every software engineers' responsibility, is not solely to generate code. It is also to build and maintain a theory of the systems we architect, implement, and support. Based on Gilbert Ryle's definition of a theory, the implication is that we are ultimately responsible for ensuring that our team and organization can: detect and correct lapses in our systems, learn from our mistakes, explain and justify our choices, answer queries about our developments, argue about our approaches, etc. For an individual, this is not difficult; we have complex minds that can assemble theories automatically. But we cannot distribute and align our theories without conscious efforts and external mediums. Undoubtedly, many factors play critical roles in enabling the effective distribution and alignment of theories within a team, department, and organization. In this article, I hope to contribute some thoughts on one of these factors.
Douglas Engelbart understood the importance of distributing and aligning our theories decades ago and spent his entire career encouraging organizations to care for their knowledge. That is, the collection of documents and other material supporting the endeavor of the organization. Knowledge can be anything from meeting notes, market surveys, feature requests, code reviews, bug reports, proposals, roadmaps, design specs, industry trends, etc. One of his seminal developments was the CoDIAK process, a combination of continuous analysis, digestion, and knowledge integration enhanced through technological tools and systems. At the center of his ideas is the hyper document - and the notion that it is not the individual piece of knowledge (the single meeting note, the lonely proposal, the isolated code-review) that's important, but rather, the links between the pieces of knowledge. Connections between pieces of knowledge enable navigation, making it possible to go from a roadmap to a story, to a chat thread, to a code review. And back again. Without connections, an organization's knowledge does not describe its theories.
It might be beneficial to highlight that the idea that we should place great value on the links connecting our knowledge is not unique to technology work. Niklas Luhmann, arguably one of the most prolific academic authors of modern times, dedicated much of his success to his Zettelkasten ─ a physical note-taking system with a strong emphasis on cross-references between pieces of knowledge. A Zettelkasten enables an operator to have a "dialog" with the notes and build theories from the connectedness of ideas. Although it is hard to imagine what it's like to search and navigate physical cards of knowledge, it undoubtedly enabled him to achieve great work.
In practice
But what does this mean for an organization? First, it is unlikely for a modern organization to implement a single CoDIAK system successfully. Contemporary knowledge work requires various tools and processes, which can often differ between teams, even within a single organization. Even more unlikely is for a modern organization to work through a physical Zettelkasten. However, with the increasing adoption of cloud-based software services, our organizations have growing access to hyper document systems. Indeed, web-based knowledge systems (e.g., internal wiki, online documents, chat systems, code repositories, emails, etc.) are implicitly connected, and we can (and should) link between them.
As we continue growing organizations, their theories become more complex. Simultaneously, more individuals (internal and external to our teams) will be interested in accessing and leveraging our knowledge and consuming our theories. Based on Peter Naur's, Douglas Engelbart's, and Niklas Luhmann's perspectives, I believe there are two straightforward practices that teams, departments, and even whole organizations can adopt today. First, we need to think of everything we produce as pieces of knowledge contributing to a broader theory. And second, we need to obsess about connecting our knowledge.
Practically, this means we need to transfer as much of our knowledge as possible into shareable mediums and, more importantly, connect our various shared pieces of knowledge. Concretely, this means linking the goals in our roadmap documents to the associated epics within our task tracker. But also, and perhaps not intuitively, linking back from the epic to the associated roadmap document. We need to ensure that code-reviews, chat discussions, and meeting minutes link to related pieces of knowledge. And, of equal importance, that the related pieces of knowledge link back. Effectively, we need to link and back-link extensively and generously. We do not know where someone will start their search nor which of our connections will enable someone to discover the theory they seek, but we know that no one will find a theory without connecting our knowledge.
Finally, these ideas also contextualize the raison d'être of our various systems containing our knowledge. They are tools supporting our continuous pursuit of developing and distributing our theories. And should be designed and integrated within our organizations as such. Perhaps controversially, I believe that this means that we should not think about our task-tracker as a place of estimation and work-artifact creation, but primarily as a place to communicate project knowledge. Roadmaps are not static outlines but should instead be living documents evolving as we gather new knowledge and update our theories. Code reviews are not only about the code itself but should also, through links to supporting pieces of knowledge, communicate why we have decided to do things in a certain way. Fundamentally, we must continuously strive towards making as many of the implicit connections between our knowledge explicit.
Conclusion
To care and connect our knowledge is critical to enable the formation and distribution of our theories. And our theories are essential for propelling us forward. They help us detect and correct lapses in our systems, learn from our mistakes, explain and justify our choices, answer queries about our developments, argue about our approaches, and, ultimately, build the momentum we need to pursue our visions.
Thanks to all the reviewers and Hannah Gambino for the illustrations.
Be sure to follow @doximity_tech if you'd like to be notified about new blog posts.
