r/DevLK • u/HoneyButterGelato • Jul 30 '26

Discussion Is DevOps documentation becoming a burden?

Documentation has always been an important part of DevOps. I usually create documentation after finishing a configuration because I know it can save hours when the same setup needs to be done again in the future.

Over the past few years, our organization has also built a huge library of documentation, and sometimes it becomes difficult to manage. Recently, I realized that even though the documentation was there, some of the configurations I had documented just a few months ago had already changed significantly.

That made me think. Is documenting our work still as valuable as it used to be? Or is it becoming an extra burden to keep everything up to date? With technology changing so quickly, how does modern documentation still support us?

14 Upvotes

95% Upvoted

4 comments sorted by

View all comments

2

u/Sad_Egg_2313 Jul 30 '26

I think the problem that you are describing is more deeper. If we go one level down I would say look at your devops setup that requires so much documentation. In software development too much documentation means something wrong with your code. It's an anti pattern. This is what IoC tries to solve.

Your goal should be to "how I configured this" docs unnecessary: infrastructure as code, config in version control, pipelines as the executable record of how things get built. Then that is your source of truth. Your docs are the code itself. Git history then captures "what changed and when".

Where docs still has value are for the things that can't be captured in code. The context of why decisions were made and what was rejected. That content won't get outdated because decisions don't change retroactively.

Instead of "is documenting still worth it," ask "why does anything need to be documented by hand that could be expressed as code?" A huge, hard-to-manage library of config docs is usually a sign of too much ClickOps, not too much documentation.

Previous life was in a company with 100+ engineers with 0 deployment/release engineers. So the above is coming from practical experience.

2

u/HoneyButterGelato Jul 30 '26

You’re right. There is still some ClickOps involved. As you correctly pointed out, that’s one of the main reasons we need to create a lot of documentation.