Documents & Maintenance
Artifacts are necessary for a system to be maintainable, but think of them more as a reference or as training materials, not as the primary mechanism for ensuring maintainability. For a system to be maintainable, knowledge must exist in the heads of those who will maintain it. If only documents exist, there is a substantial risk the system is not maintainable; either because the documents are inadequate, or they have not captured important design strategies (this is extremely common), or because the system is complex and it is simply too difficult for the maintainers to learn how to maintain the system from documents alone … or all of the above. Also, documentation of the internal design of software is notoriously inaccurate.
In order for a system to be maintainable, there needs to be a plan for ensuring that the knowledge of how to maintain the system is transferred when the system is transitioned to the maintenance team. The plan must address how the knowledge will be maintained over time as the system evolves and as people come and go. A system of apprenticeship, in essence, is needed and the level of knowledge of the system’s design must be tracked as an important asset to be maintained. This is usually not done, and, as a result, many legacy systems today are in a situation where no one can maintain them. Yet, no one can replace them because no one knows exactly what they do. The costs of this state of affairs can be large: inability to act (a lack of business agility), and chronic technical problems that cannot be properly addressed.
One strategy for preventing this untenable situation is to involve the individuals who will actually maintain the system in the creation of the maintenance plan, and simply pose the requirement that the system continue to be maintainable over time. In any case, both the system owner and the enterprise should actively track the level of knowledge and capabilities of the maintenance team, rather than treating this activity as a low-skill sideline task, as is often the case.
Please read more about how to create a non-document centric software development environment in my book Value-Driven IT.
Cliff Berg is a consultant in IT process, methodology, and change management, and a former enterprise system architect. Cliff has written four books, most recently Value-Driven IT, and before that High-Assurance Design. Previously Cliff was founder and CTO of Digital Focus, now Command Information.