“If only they had written a better design document” complained the (to remain unknown) architect in frustration after a series of “he said”, “she said”, and “no, that’s not what I meant”. Software development is tricky business and more so the larger the system. Large systems mean more people with smaller pieces of responsibilities (relative to the whole) necessitating more communication to ensure a cohesive system. And our faulty memory makes it wise to document the design.
But what stops us from writing better documentation? What do we mean by “better”?
Architects write documentation to communicate what we know about the software. Software is difficult to observe, see or feel unlike the way we can with buildings. Yes, we can see its user interface, but that’s like attempting to assess the shape, size, location, direction and speed of an iceberg based on an aerial photo. Software architecture is, at its core, a knowledge management problem.
Knowledge is the awareness, understanding and experience with the collected information, where information convey data and their relationships (Zins, 2007). Within a project context, either three (knowledge, information and data) is: documented or undocumented; and implicit or explicit – as illustrated in figure 1 and described by Kruchten, Lago, and Vliet (2006).
The implicit, undocumented knowledge includes what we don’t know what we don’t know. But it also includes people’s experience or intuition (gut feel), as well as the “of course” knowledge. We use checklists and methodologies to cover us against what we don’t know, we hire good people to gain the best experience, however, the “of course” knowledge is difficult to quantify, as we might be unaware. “Of course” is a risk to the project; what is obvious to you is not obvious to the team. If projects are large enough, then people will also build up a certain amount implicit knowledge about the project, its deliverables, and involved teams and systems.
The implicit, but documented knowledge is the unattainable – either because we lost or cannot find the manual, incomprehensible (source code), or inaccessible due to contractual or intellectual property limitations. Old systems or third-party developed software will contribute to this category.
The explicit, yet undocumented knowledge cover our observations, the water cooler discussions, and general awareness which we can articulate. This knowledge will quickly become implicit knowledge if it is not documented. And similar to the implicit knowledge, people working as part of large projects will build up this type of knowledge about the project and associated systems.
The last category is what we deliver – explicit, documented knowledge about the new system. However, the problem is to get all of the relevant knowledge into this category.
Can we do that? No.
Nonaka (1991) identified four knowledge creating processes in his seminal HBR article “The Knowledge-Creating Company”. Rather than just walk you through the four processes, figure 2 attempts to illustrate them.
The first part involves observations to gather tacit data. If we observe data (aka analyse) then we may find information. This we may be able to articulate into explicit information, which we can then organise into documents with text, charts and diagrams. We can then take the explicit information and apply it within a context to solve a problem or support a decision (the tacit knowledge). And observations about tacit knowledge form a critical part of architectural evaluations such as ATAM.
The problem is that these knowledge creating processes (illustrated as arrows) don’t retain information or knowledge perfectly – some gets left behind. And each of them creates new implicit knowledge – typically in the form of experience – which can be difficult to capture accurately. Knowledge is elusive by nature and therefore challenging to capture perfectly.
To create better documentation, we need to “deliver” all three types of sharable knowledge:
- Tacit/implicit – that is mostly in people’s heads. We may be able to express it and thereby make it explicit; or we may not. The portion we can articulate, we deliver through presentations, workshops and other forms of meetings.
- Documented – it exists in a written form (email, notes, whiteboard, or word processing document). While these are important during data gathering and analysis to create information, we need to create a formal home either as an appendix or separate support documentation.
- Formal refers to not only the documented form, but also that it is structured in some systematic way using a modelling language (e.g. UML, ArchiMate, SysML, etc.).
Better architectural documentation must address all three types of knowledge, their role in the creation process, and their relationships.