DevOps.com

  • Latest
    • Articles
    • Features
    • Most Read
    • News
    • News Releases
  • Topics
    • AI
    • Continuous Delivery
    • Continuous Testing
    • Cloud
    • Culture
    • DevSecOps
    • Enterprise DevOps
    • Leadership Suite
    • DevOps Practice
    • ROELBOB
    • DevOps Toolbox
    • IT as Code
  • Videos/Podcasts
    • DevOps Chats
    • DevOps Unbound
  • Webinars
    • Upcoming
    • On-Demand Webinars
  • Library
  • Events
    • Upcoming Events
    • On-Demand Events
  • Sponsored Communities
    • AWS Community Hub
    • CloudBees
    • IT as Code
    • Rocket on DevOps.com
    • Traceable on DevOps.com
    • Quali on DevOps.com
  • Related Sites
    • Techstrong Group
    • Container Journal
    • Security Boulevard
    • Techstrong Research
    • DevOps Chat
    • DevOps Dozen
    • DevOps TV
    • Digital Anarchist
  • Media Kit
  • About
  • AI
  • Cloud
  • Continuous Delivery
  • Continuous Testing
  • DevSecOps
  • DevOps Onramp
  • Practices
  • ROELBOB
  • Low-Code/No-Code
  • IT as Code
  • More
    • Application Performance Management/Monitoring
    • Culture
    • Enterprise DevOps

Home » Features » Documenting: Don’t Build Your Replacement’s Nightmare

Insider knowledge documenting

Documenting: Don’t Build Your Replacement’s Nightmare

By: Don Macvittie on July 23, 2020 1 Comment

Want to reduce headaches tomorrow? Document everything today

Recent Posts By Don Macvittie
  • Who Controls Your Build Process?
  • Lock Down Your Toolchain
  • Filter the Firehose
More from Don Macvittie
Related Posts
  • Documenting: Don’t Build Your Replacement’s Nightmare
  • Understanding the App Development Life Cycle
  • Empathy for the API Developer
    Related Categories
  • Blogs
  • DevOps Practice
  • Features
    Related Topics
  • continuous documentation
  • documentation
  • Enterprise IT Operations
  • technical debt
Show more
Show less

About once a year I feel the need to remind you that you are creating technical debt. DevOps is good stuff, and most shops got over the “whatever a given project team decides” multiplication of services pretty quickly, but every line of DevOps code you write is creating technical debt.

There is no way around this fact. You are writing code (scripts, if you prefer) and developing configs that make assumptions. Those assumptions will change—products will get incompatible upgrades, vendors will go under, libraries will become outdated … the list goes on.

We have a long history with technical debt. DevOps partially grew out of the need to spend less time maintaining and more time releasing features, and yet we’re re-creating technical debt; in some cases at a much larger scale. It is unavoidable but can be managed. Keep a reference list of assumptions—“This app assumes environment contains X,” or “This app supports Cisco Network APIs version X.Y”—so you know where to look when things inevitably go wrong. The list conveniently doubles as a handy reference to what needs updating when you find out your middleware vendor is going under or that MySQL is out and MariaDB is in.

The more cutting-edge tools you use, the more likely that you are baking future problems into your environment. This is not advice to avoid cutting-edge; it is advice to recognize reality and keep closer track as you move new things into your environment that might be half-baked or whose market is destined for consolidation.

Our IT environment has become super-complex. DevOps helps us manage that complexity but discourages adequate documentation. We’ve all heard, “It’s self-documenting” (no, it’s not) or “There is basic documentation” (basic almost always means, “We scratched some notes when it was first set up”… and haven’t touched them since). Don’t do that. Make sure that the new guy after all of you have left can figure out what is going on in this highly complex environment. It is not up to new people to be super-learners with mind-reading skills; it is up to implementors to make certain new people can figure out what is going on without wasting 5,000 hours pawing through scripts.

It does not take much time to document dependencies. It doesn’t take much more to document relationships. Future you will be grateful when they walk in and need to come up to speed in a short amount of time. Because it doesn’t matter how automated it is when the automation breaks—it matters how quickly staff on hand can fix it and get things going smoothly again.

You’re keeping the world running. Take a second and make sure the next person can, too. And keep rocking it.

Filed Under: Blogs, DevOps Practice, Features Tagged With: continuous documentation, documentation, Enterprise IT Operations, technical debt

Sponsored Content
Featured eBook
The State of the CI/CD/ARA Market: Convergence

The State of the CI/CD/ARA Market: Convergence

The entire CI/CD/ARA market has been in flux almost since its inception. No sooner did we find a solution to a given problem than a better idea came along. The level of change has been intensified by increasing use, which has driven changes to underlying tools. Changes in infrastructure, such ... Read More
« Vercel Makes Front End Applications Faster
Serverless Computing: Taking DevOps to the Next Level »

TechStrong TV – Live

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

Upcoming Webinars

Bring Your Mission-Critical Data to Your Cloud Apps and Analytics
Tuesday, August 16, 2022 - 11:00 am EDT
Mistakes You Are Probably Making in Kubernetes
Tuesday, August 16, 2022 - 1:00 pm EDT
Taking Your SRE Team to the Next Level
Tuesday, August 16, 2022 - 3:00 pm EDT

Latest from DevOps.com

Techstrong TV: Scratching the Surface of Testing Through AI
August 12, 2022 | Alan Shimel
Next-Level Tech: DevOps Meets CSOps
August 12, 2022 | Jonathan Rende
The Benefits of a Distributed Cloud
August 12, 2022 | Jonathan Seelig
Cycode Expands Scope of AppDev Security Platform
August 11, 2022 | Mike Vizard
Techstrong TV: The Use of AI in Low-Code
August 11, 2022 | Charlene O'Hanlon

Get The Top Stories of the Week

  • View DevOps.com Privacy Policy
  • This field is for validation purposes and should be left unchanged.

Download Free eBook

The Automated Enterprise
The Automated Enterprise

Most Read on DevOps.com

CREST Defines Quality Verification Standard for AppSec Testi...
August 9, 2022 | Mike Vizard
Leverage Empirical Data to Avoid DevOps Burnout
August 8, 2022 | Bill Doerrfeld
MLOps Vs. DevOps: What’s the Difference?
August 10, 2022 | Gilad David Maayan
We Must Kill ‘Dinosaur’ JavaScript | Microsoft Open Sources ...
August 11, 2022 | Richi Jennings
GitHub Brings 2FA to JavaScript Package Manager
August 9, 2022 | Mike Vizard

On-Demand Webinars

DevOps.com Webinar ReplaysDevOps.com Webinar Replays
  • Home
  • About DevOps.com
  • Meet our Authors
  • Write for DevOps.com
  • Media Kit
  • Sponsor Info
  • Copyright
  • TOS
  • Privacy Policy

Powered by Techstrong Group, Inc.

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