Continuous DevOps documentation: It's a necessity

Modern software delivery is all about dropping the red tape and gates, right? Well, not really. The processes of documentation and governance are still what keep companies out of trouble and allow the working men and women to keep their jobs. The fact that documentation and governance have been synonymous with slow is a matter of historical baggage. The same automation we bring to software releases also can be applied to documentation. And DevOps documentation is not going away: it's transforming.

If we are realistic about how IT organizations documented their infrastructure and processes in the past, we would come to the conclusion that it has been broken all along. The vast majority of the documentation effort was spent on information that was never used. And the core drivers of documentation efforts were to check boxes, not actually to benefit the team. The problem is that information was spotty. Documentation is created in a waterfall fashion, rarely updated, highly prone to human error and lacking consistency. Sometimes teams were just too busy to finish documentation that inevitably was abandoned altogether.

However, when it came time to resolve issues, and accelerate time to recovery, documentation was the only option to know what configurations are and what is going wrong with them. So, when documentation is used as a reason to avoid expedited modern development, it is an unfair excuse.

In a DevOps delivery chain, manual documentation is not an option. And many think documentation goes away altogether. But really it's dramatically improved. Documentation in modern development does not go away, although its generation and purpose have changed completely.

In fact, the generation of documentation is so transparent that it often seems absent altogether. Savvy DevOps shops will put in a deliberate effort to collect application and log data in real time. They will store that information into a smart log analysis platform, and build awesome alerting on top of it, all to keep track of what is going on and respond to it. But what they do not realize is that at the same time, they have built an automated documentation system.

The sources of DevOps documentation are:

1. Code
2. Configuration management scripts
3. Application performance logs
4. Infrastructure logs
5. Alerting tools and alerts
6. Component monitoring

It may not be the original driver to use these systems for documentation, but that is exactly what is happening in the DevOps process:

• Proper application architecture alone can lead to quality documentation via the popular design architecture model view controller and automated documentation creation.
• Configuration scripts such as Puppet and Chef are documenting servers. A script provides a clear picture of how all the infrastructure that is in production was set up.
• Application performance management and server logs become a historical view of the application and infrastructure.
• Alerting tools become a history of all that has gone wrong and how a response was formed.
• Component monitoring tools show what components are being used, and if and when there have been updates or issues associated with them.

All of these tools and processes replace the need to create documentation manually, and, collectively, they make up the entirety of your environment's documentation. Something I call continuous documentation. They do it with much greater coverage than manual documentation ever could. It may not look like that huge Word document with a lot of screenshots, but its value is the same.

However, continuous DevOps documentation must be implemented with proper adoption and with a plan. If you do not decide on how you are going to consume the information, then its value will be lost quickly.

Its benefits go far beyond the record. For new team members it is an easy way to train them and ramp up. Just a week of having eyeballs on these tools will give new team members a much clearer picture of how things are set up than direct lessons could. It also avoids the need to find subject matter experts when things do go wrong, because it is all right there without the need to specifically grab it. Greater coverage than traditional IT could imagine.

DevOps documentation does not go away. Its transformation dramatically improves the way documentation is used. Now, documentation generation is automatic, its usage is deliberate and more frequent, and it is action oriented, not reactive.

Have you found continuous documentation to be a struggle in a DevOps world? Let us know.