For a software architect, and someone who tinkers with words, this is perhaps an odd thing to say, but it is true: I hate documentation.
I hate it because it is laborious, very often serves no purpose other than to have been produced, and rapidly gets out of date. I have followed methodologies where every model under the sun is produced, code is generated, and round-trip engineering is attempted. What were we thinking?
But documentation can add value. Code is a very low-level, cumbersome way to get to grips with a system. A few high-level component or sequence diagrams can add a lot of value. Documentation helps you to navigate a system, and understand why something was built.
So what to do?
I think the first thing to do is to distinguish between transient and permanent documentation.
Transient documentation is correct at a point in time, and very often only exists on a whiteboard. It serves to help think about a solution, but has a very short life span. After it has served a purpose, it gets to rest in peace in some archive.
Permanent documentation, however, continues to exist alongside the system, a living description that helps one to understand what was built. Permanent documentation needs to be owned and managed. And being managed, needs to be kept up to date. This means that if a project impacts the system, the owner(s) of the permanent documentation of that system need to be notified, so that the documentation can be updated. Of course this is costly, so you do it only to documents you care about.
But this is not the end of the story. Generating navigable documentation from your systems is a powerful way of supplementing your formal documentation. For example:
I hate it because it is laborious, very often serves no purpose other than to have been produced, and rapidly gets out of date. I have followed methodologies where every model under the sun is produced, code is generated, and round-trip engineering is attempted. What were we thinking?
But documentation can add value. Code is a very low-level, cumbersome way to get to grips with a system. A few high-level component or sequence diagrams can add a lot of value. Documentation helps you to navigate a system, and understand why something was built.
So what to do?
I think the first thing to do is to distinguish between transient and permanent documentation.
Transient documentation is correct at a point in time, and very often only exists on a whiteboard. It serves to help think about a solution, but has a very short life span. After it has served a purpose, it gets to rest in peace in some archive.
Permanent documentation, however, continues to exist alongside the system, a living description that helps one to understand what was built. Permanent documentation needs to be owned and managed. And being managed, needs to be kept up to date. This means that if a project impacts the system, the owner(s) of the permanent documentation of that system need to be notified, so that the documentation can be updated. Of course this is costly, so you do it only to documents you care about.
But this is not the end of the story. Generating navigable documentation from your systems is a powerful way of supplementing your formal documentation. For example:
- using tools like Swagger to generate invokable service interface documentation.
- using deployment scripts to publish deployment information to configuration management database systems such as Service Now.
- using application performance monitoring technology like AppDynamics to show system deployments and interactions.
- using standardised logging and log aggregation (operational intelligence) tools like Splunk to help trace message flows through systems.