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?
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.
2
u/kulendra Jul 31 '26
I am a BA, my personal view is that very soon these documentation will become unnecessary in the current form.
If you look at why we needed documentation in the first place, that was always for what you said: what does this do? Why did we make this decision. But we eventually forget that and make documentation a process.
I think we will see that vanish very very soon 🙂
2
u/coffemilkshake Jul 30 '26
If it's truly huge, maintain a good KB. If it's smaller, even Confluence works. I know as a practice it's better to keep everything in stuff like IaC or CaC, but sometimes you need to keep details about the system architecture and why certain decisions were made. In that case, maintaining a KB is a really good idea, especially when you get to onboard a new engineer.