DevOps.com

  • Latest
    • Articles
    • Features
    • Most Read
    • News
    • News Releases
  • Topics
    • AI
    • Continuous Delivery
    • Continuous Testing
    • Cloud
    • Culture
    • DataOps
    • DevSecOps
    • Enterprise DevOps
    • Leadership Suite
    • DevOps Practice
    • ROELBOB
    • DevOps Toolbox
    • IT as Code
  • Videos/Podcasts
    • Techstrong.tv Podcast
    • Techstrong.tv - Twitch
    • DevOps Unbound
  • Webinars
    • Upcoming
    • On-Demand Webinars
  • Library
  • Events
    • Upcoming Events
    • On-Demand Events
  • Sponsored Content
  • Related Sites
    • Techstrong Group
    • Container Journal
    • Security Boulevard
    • Techstrong Research
    • DevOps Chat
    • DevOps Dozen
    • DevOps TV
    • Techstrong TV
    • Techstrong.tv Podcast
    • Techstrong.tv - Twitch
  • Media Kit
  • About
  • Sponsor
  • AI
  • Cloud
  • Continuous Delivery
  • Continuous Testing
  • DataOps
  • DevSecOps
  • DevOps Onramp
  • Platform Engineering
  • Low-Code/No-Code
  • IT as Code
  • More
    • Application Performance Management/Monitoring
    • Culture
    • Enterprise DevOps
    • ROELBOB
Hot Topics
  • HPE to Acquire OpsRamp to Gain AIOps Platform
  • Oracle Makes Java 20 Platform Generally Available
  • How to Maximize Telemetry Data Value With Observability Pipelines
  • Awareness of Software Supply Chain Security Issues Improves
  • Why Observability is Important for Development Teams

Home » Blogs » Doin' DevOps » Continuous Documentation

Continuous Documentation

Avatar photoBy: Chris Riley on March 30, 2015 7 Comments

Is documentation dead in DevOps? Yes and no. It is transformed, it is automatic, and it is actionable.

Recent Posts By Chris Riley
  • Using Incident Response for Continuous Testing
  • What Is Resilience Engineering?
  • Moving from NOC to the SRE Model
Avatar photo More from Chris Riley
Related Posts
  • Continuous Documentation
  • Cloud-Based Documentation at the Speed of DevOps
  • The Value of Documentation
    Related Categories
  • Blogs
  • Doin' DevOps
    Related Topics
  • devops
  • documentation
Show more
Show less

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.

Filed Under: Blogs, Doin' DevOps Tagged With: devops, documentation

« Making DevOps Work with External Contractors
Reducing Incident Resolution Time »

Techstrong TV – Live

Click full-screen to enable volume control
Watch latest episodes and shows

Upcoming Webinars

The Testing Diaries: Confessions of an Application Tester
Wednesday, March 22, 2023 - 11:00 am EDT
The Importance of Adopting Modern AppSec Practices
Wednesday, March 22, 2023 - 1:00 pm EDT
Cache Reserve: Eliminating the Creeping Costs of Egress Fees
Thursday, March 23, 2023 - 1:00 pm EDT

Sponsored Content

The Google Cloud DevOps Awards: Apply Now!

January 10, 2023 | Brenna Washington

Codenotary Extends Dynamic SBOM Reach to Serverless Computing Platforms

December 9, 2022 | Mike Vizard

Why a Low-Code Platform Should Have Pro-Code Capabilities

March 24, 2021 | Andrew Manby

AWS Well-Architected Framework Elevates Agility

December 17, 2020 | JT Giri

Practical Approaches to Long-Term Cloud-Native Security

December 5, 2019 | Chris Tozzi

Latest from DevOps.com

HPE to Acquire OpsRamp to Gain AIOps Platform
March 21, 2023 | Mike Vizard
Oracle Makes Java 20 Platform Generally Available
March 21, 2023 | Mike Vizard
How to Maximize Telemetry Data Value With Observability Pipelines
March 21, 2023 | Tucker Callaway
Awareness of Software Supply Chain Security Issues Improves
March 21, 2023 | Mike Vizard
Why Observability is Important for Development Teams
March 21, 2023 | John Bristowe

TSTV Podcast

On-Demand Webinars

DevOps.com Webinar ReplaysDevOps.com Webinar Replays

GET THE TOP STORIES OF THE WEEK

Most Read on DevOps.com

Large Organizations Are Embracing AIOps
March 16, 2023 | Mike Vizard
Modern DevOps is a Chance to Make Security Part of the Process
March 15, 2023 | Don Macvittie
Addressing Software Supply Chain Security
March 15, 2023 | Tomislav Pericin
What NetOps Teams Should Know Before Starting Automation Journeys
March 16, 2023 | Yousuf Khan
DevOps Adoption in Salesforce Environments is Advancing
March 16, 2023 | Mike Vizard
  • Home
  • About DevOps.com
  • Meet our Authors
  • Write for DevOps.com
  • Media Kit
  • Sponsor Info
  • Copyright
  • TOS
  • Privacy Policy

Powered by Techstrong Group, Inc.

© 2023 ·Techstrong Group, Inc.All rights reserved.