Is documentation dead in DevOps? Yes and no. It is transformed, it is automatic, and it is actionable.
Back in the days of waterfall development, documentation always seemed to be the unwanted stepchild — it was an afterthought, a theoretically necessary chore that frequently went undone. And there were understandable reasons for this. For one thing, development documentation (as distinct from end-user manuals) didn’t actually add to the immediate value of the software being produced. Any value that documentation did add came later — perhaps years later — when the code was being revised or debugged. In the short term, the effort required to document code const extra money and required extra time. It could only be justified on the basis of possible future utility.
But modern programming practices, centered around Agile methodology and DevOps, have given documentation a new and very different life. It would be easy to imagine that there is simply no place for documentation in a DevOps world, with its emphasis on continuous deployment. You can’t stop the conveyor belt to document everything that’s coming down the line — it’s much more important to keep the process moving. And even if you could stop the deployment process to document it, you would only get occasional snapshots, and not a picture of the ongoing process.
Modern documentation, however, doesn’t require the conveyor belt to be stopped at all. It is in fact, a continuous process in its own right, automatically generated as an intrinsic part of continuous deployment itself. There is as much useful information built into the Continuous Deployment model as there is in formal waterfall-process documentation; it merely assumes different forms, and comes from different sources. The automated processes that drive and control DevOps generate logs, which form an ongoing stream of documentation. The Application Performance Monitoring (APM) system monitors and logs post-deployment performance and alerts. All of this data is channeled into the log analysis platform, which serves as a natural clearing-house for collecting, recording, organizing, and analyzing the automatic documentation stream.
The scripts which control the automated DevOps processes also serve as a form of documentation. They include information about system, server, and software configuration, and they serve as a detailed generic record of the deployment process. They become even more valuable as documentation when they are combined with the logs of deployment status updates, which form timestamped records of individual deployments, and which can serve as a source for historical deployment statistics.
At some stages of testing (largely those most closely connected with deployment), automated testing scripts and logs can serve as useful documentation. Taken together with issue and project tracking records (as well as alert logs), they may serve to pinpoint recurring or chronic problems, as well as providing a general quality-control history.
These are just the most obvious examples; there are other, similar sources of documentation throughout the DevOps processes. What all of these documentation channels have in common is that they are almost entirely automated. A few types of documentation, such as issue tracking, may require some manual input, but by and large they are automatically generated by the DevOps processes themselves. No extra effort at all is required to produce this documentation; it is already there by default. This, more than anything, is what distinguishes it from old-style waterfall development documentation.
The challenge of modern development documentation is twofold: recognizing what is available, and understanding how to make use of it. Because they already exist as part of the process or are produced automatically, it is easy to overlook many of the key elements of modern documentation. Most DevOps tools come with some kind of logging or reporting functionality, but the DevOps team may not be aware of them, or may only use the default logging/reporting features. It is important to understand the logging and reporting capabilities of all of the tools being used, and to recognize what kinds of data are being logged.
When you know what data is available, you can look at the best ways to integrate it into your log analysis system, and you can develop a better understanding of what data will be most useful to you. Integrated log analysis involves the technical team as much as it involves the logs themselves; otherwise much of the value of the integration will be lost. In the same way, understanding what you want requires a DevOps-wide set of use cases, so that you can determine which elements of the documentation stream are the most important to you.
This kind of preparation is the key to making effective use of continuous documentation. If you can determine from the start what kinds of information you may need to pull from the documentation stream, you can have the reports, alerts, and queries in place, so that checking the documentation for a given item will be a quick, automatic process, and not an improvised “let’s reinvent the wheel each time we do this” search. Continuous documentation shouldn’t be a manual effort; in order to function properly or even at all, in fact, it must be automated.
There are, of course, still applications where traditional documentation (and waterfall development) will persist. But it is important to emphasize that traditional documentation requires waterfall development or the equivalent, because it is the result of added effort after most of the development cycle is complete. It will only work when there is an after at the end of the cycle. In DevOps, there is no end to the cycle and there is no after; there is only continuous development or a series of sprints, so there is no choice but to maintain a continuous stream of documentation. It is not an option; it is built into the system.
As we have seen, however, this is the great strength of continuous documentation. It is always there, and you only need to understand what is available, what is important to you, and how to automatically organize and channel that flow of data to best suit your purposes.
