Is documentation debt a real problem or just something engineers complain about?
Posted by Personal-Brilliant14@reddit | sysadmin | View on Reddit | 56 comments
Honest question for engineering teams: is documentation debt something that actually keeps you up at night, or is it one of those problems everyone complains about and then just learns to live with? I'm trying to figure out if people genuinely want this solved or if it's just a universal gripe that nobody actually prioritizes fixing. Would love to hear how your team actually handles it in practice.
reinhart_menken@reddit
Is this like another thing someone/you are going to vibe code and/or try to sell or you're a student or that? Cause if you work in our field you'd know the answer already.
tarvijron@reddit
Oh shit you called it.
reinhart_menken@reddit
Haha seen too many of these.
Personal-Brilliant14@reddit (OP)
Fair skepticism, and I respect it. 12 years in, I've lived this pain firsthand, not read about it. This isn't a vibe-coded weekend project, it's me trying to validate whether the people who feel this pain most are actually willing to pay to make it go away before I build anything serious. So your answer genuinely matters here.
MaNbEaRpIgSlAyA@reddit
Brother why are you using ChatGPT to write your Reddit comments? Brain broken 🤖
tarvijron@reddit
Reddit broken. Internet broken. Reject computer, embrace fiber crafts. Return nature.
Personal-Brilliant14@reddit (OP)
I don't have a good command on my grammer, so always afraid of writting online. Yes I used chatgpt but with honest intent to improve life of people.
throwaway_eng_acct@reddit
lol. lmao, even. Your “honest intent” is to use this subreddit for market research and try to sell us some vibecoded slop app. You’re being completely dishonest in every part of this interaction.
Personal-Brilliant14@reddit (OP)
That's exactly the cycle, right? The pain is acute for a few weeks and then everyone forgets about it until it hits them again. What if the tool just ran in the background and kept documentation current automatically, so by the time the next person joins it's actually useful instead of a liability
tarvijron@reddit
It’s something that causes great agitation for the onboarding period and then completely falls off the radar until the next person leaves/joins the team.
Personal-Brilliant14@reddit (OP)
That's exactly the cycle, right? The pain is acute for a few weeks and then everyone forgets about it until it hits them again. What if the tool just ran in the background and kept documentation current automatically, so by the time the next person joins it's actually useful instead of a liability. Would that be something worth paying for?
Inquisitor_ForHire@reddit
I'll bite. How is it gathering this data for documentation? What hooks does it have? What APIs can it talk to? This feels like it would take a LOT of setup to get working.
Personal-Brilliant14@reddit (OP)
That is the tricky part and didn't think much. For MVP, can start with github source code and user can run a command to start the documentation.
Inquisitor_ForHire@reddit
Ahh so just documenting Github. No thanks. I don't use Github. I'd rather have something that hooks into CMDB systems, finds all the objects, then starts checking those things against DNS, AD, Network Scans, etc etc. Not an easy thing to do at all. This is a very very very large pie you're trying to take a bite out of.
Personal-Brilliant14@reddit (OP)
This is interesting. Wondering what do you document here? If I understand correctly you would require a system to visualize the dynamic data coming in from CMDB systems?
Inquisitor_ForHire@reddit
You're in r/sysadmin asking about documentation. We have to document EVERYTHING. Every server. Every switch. Every system. Every application. How is that web server configured? How is DNS configured? What's the password policy? What are the trusted roots in the certificate authority. None of that is going to be in github in any organization.
We do Devops on a 18k server footprint. Everything about our builds is documented automatically. The stuff that's in repos is EASY to deal with. It's the shit that isn't in repos that's the killer. You know what kills most IT staffs every single day? Legacy shit. Figure out how to document that and I'll talk to you. :)
throwaway_eng_acct@reddit
Ughhhh go away please. Nobody is going to buy your vibe coded AI slop.
locke577@reddit
So not an honest question. Astroturfed ad campaign.
fnordhole@reddit
Yup. Tired if this crap.
If I see "I built an app that..." one more time...
Yuugian@reddit
If your Vibe-coded AI tool can be run COMPLETELY offline, probably not but maybe. Otherwise: absolutely not.
Keeping up with inventory and basic documentation is something that should be part of the Sysadmin job and is partially to make sure we did all the parts that are required. Even if it's just a checklist and shared note page kept in a shared/searchable file repo. It will help the jr catch up and help the Sr keep tabs on what's changing
MissionBusiness7560@reddit
This 100x
OneSeaworthiness7768@reddit
lmao no, of course not. This is market research.
Personal-Brilliant14@reddit (OP)
My first post on Reddit. Have been really trying hard on Linkedin to find people who can really describe the pain. Loved the honesty and openness of the people on this group. I apologize for pulling up wrong threads in your hearts. I want to genuinely solve a problem that is really hard, but want to ensure if that problem is actually pain that people face every day.
OneSeaworthiness7768@reddit
You have a solution in search of a problem. Wrong way to develop an idea.
Personal-Brilliant14@reddit (OP)
How would you approach to develop an idea? I have failed miserably thrice working with the current model your described. So this time I haven't started coding at all and validating with people if the problem exist. From this thread conversation it seems like the problem and pain is real. Regarding the solution I don't know how will it work.
lotekjunky@reddit
documentation is overrated. ai can spit it out at an alarming rate making it completely avoidable and useless for future engineering. BUT! Big but here... drawings are critical and important. you can currently have an llm generate mermaid or drawio images and it gets REALLY close with my testing. I fed it some shitty xml from an ancient workflow system and it made the image almost perfect... and it's easy though to fix. No more visio for me.
Personal-Brilliant14@reddit (OP)
I used cursor to explain me the code structure and ask it to built sequence, flow and component diagrams that helps to understand data flowing in the system. Best part is AI is able to draw much better diagrams than I am able to and iterating with it is really faster. Save lot of time.
Burgergold@reddit
Documentation is a double edge
No documentation is an issue everyone can agree to. But too much documentation and not up to date is also very bad.
Personal-Brilliant14@reddit (OP)
Exactly, the sweet spot isn't more documentation, it's documentation that stays true. Tying it to the PR cycle makes sense because that's already where the change is happening. The context is right there, the diff is right there, it just never makes it into the docs. What if it did that automatically without the engineer having to do anything extra?
throwaway_eng_acct@reddit
What if you were just honest that you were trying to sell us something?
Personal-Brilliant14@reddit (OP)
I don't have anything to sell yet and I promise I wouldn't do that on reddit. Just starting to validate the pain that I have felt my whole life. I want to check if people like me are felling the same pain.
-King-K-Rool-@reddit
This, nobody talks about over-documentation but that shit is annoying. I had one job where they handed me a 5000 page OneNote where the same issue would have 5 different pages about it all saying different shit and youd have to figure out which information was current and if you asked people anything they'd say "did you check the onenote?" You'd respond with "the onenotes trash and flooded with outdated info" and they'd just chuckle and hit you with "yaaaa, we gotta clean that up sometime"
Personal-Brilliant14@reddit (OP)
Outdated documentation just sucks and completely wastes one's time.
Demented_CEO@reddit
I wouldn't say there's such a problem as "too much documentation". Sounds more like a problem of scope. We have had a Senior Documentation Specialist on the team as well and keep an extensive set of documentation available for the very reason that our environment evolves rather quickly and we need something to reference so we can avoid wasting everyone's time on why certain decisions were made.
So, there's decision documentation. Similar to a reference of an already in production, done project. This answers the "why" of the project and its parts. Then, we have technical documentation. That answers the "how" and is mostly screenshots accompanied by brief explanations so we can easily recreate something if we lose it and the backups are also gone. Lastly, we have user facing service descriptions, aka the "what".
Scoped like that, no documentation for any service or project is "too much". Stakeholders? Look at the service description. This is important to the company, it's written right there what it is about. Support engineers? Technical documentation is your friend. It tells you how that thing works. Sysadmins? Decision documentation. That answers the evergreen "why the fuck did we do this like that X years ago?"
Personal-Brilliant14@reddit (OP)
How do you maintain decision documentation? How easy is to track each of the decision doc? Would this only work if entire team takes an effort to maintain these?
Nyther53@reddit
My help desk techs at my org have gotten it into their heads that they should document everything they encounter, and are slowly, painfully, and very badly recreating Microsoft's KB in-house.
Last week someone made a document for how to change an email address in AD. This was after he couldn't figure it out on his own and escalated the ticket. So I took the time to walk him through it personally.Â
Personal-Brilliant14@reddit (OP)
Feels like document the documented. Sometimes it is hard to go through a vast documentation and more reason for this pattern to come into existence.
Man-e-questions@reddit
Yep, and that seems to happen everywhere i have worked. I personally prefer no documentation to outdated documentation. Outdated documentation makes me waste time looking for it, finding it, then trying steps in it until i realize its outdated. Sometimes it can be a substantial waste of time.
pugs_in_a_basket@reddit
Honest question back to you: Do you remember everything? That thing from 15 years ago, git blame gets you just someone reformatting something.
Do you remember a thing you did 10 years ago? You did? Oh, but it said you did a thing. Not how or why?Â
In general, do you remember everything, like we did x, and y, and why? Half a year, maybe, a year unlikely, several years did we do x, y? No, maybe, no...did we?
Document everything. For yourself, or other people following you.
ludlology@reddit
ai slop post from an anonymized fake account. probably fishing for some stupid linkedin post to promote a saas meme
tarvijron@reddit
I’m usually the guy saying this and I fucked up this one.
ludlology@reddit
it happens
gnopgnip@reddit
It depends a lot on how well the company retains experienced employees
Personal-Brilliant14@reddit (OP)
Agreed, long-tenured employees don't really need documentation. But when the team is growing, those same people get bogged down transferring knowledge?
throwaway_eng_acct@reddit
What’s the name of the app you’re trying to sell us?
MashPotatoQuant@reddit
I am right at home without documentation and in a new and unknown environment. I like exploring, finding facts about the environment and how it's configured, but a lot of people don't think that is much fun.
I would say lack of ANY documentation is usually the a sign of an overworked or unaccountable shop. Almost everywhere has some documentation to start things off, but more often than not it's old or only shows part of the true picture.
Personal-Brilliant14@reddit (OP)
That's a really interesting take. So for someone like you who actually enjoys the exploration, would a tool that connects directly to the codebase and helps map out an unknown environment be useful? And would it be something you'd pay for?
throwaway_eng_acct@reddit
The idea, yes. Your vibe coded AI slop, no.
MashPotatoQuant@reddit
Would not pay for it. If we needed such a tool, we would use something established or roll our own piping into an LLM or something.
First_Slide3870@reddit
Who types like this? This AI slop.
Ragepower529@reddit
Documentation is a constant thing… having to update it none stop is an issue and not enough is also an issue. There is no real answer for this because that would need to be a part of a culture shift…
Corgilicious@reddit
The problem is, no one values the documentation until it’s not there. The logical solution is that you build the creation of the documentation into the development just as you do testing. But of course when timelines get tight and push comes to shove, documentation is the one thing that people overlook and just throw it on the pile of something to do later. Often that later and never happens. So then the people that have the knowledge mean transition to other roles or even leave the organization, and then you’re fucked.
toilet-breath@reddit
I have used it as an excuse, a justified excuse that the reason project X takes so long is the documentation is lacking
sitesurfer253@reddit
My problem with documentation is when greener staff (or honestly senior staff that have been skating by all of their career without actual troubleshooting skills) expect every single thing to be handed to them in a KB.
If something is specific to your environment like a config or something that comes up often enough that having a step by step tutorial is helpful, absolutely, document the shit out of that.
But when I get "where is that documented?" from some smug little helpdesk tech that is trying to make the tier 2/3 teams look bad, it gets frustrating when the answer is "that information is freely available on your preferred search engine".
Document whatever is not easily Googleable (notice I said easily. If you spent hours fixing a problem, there better be some great and easy to follow information that is somewhere easy to find for people), but don't sit there and waste time making a KB for every little thing when it's the first 12 entries at the top of Google.
EngineeringApart4606@reddit
It’s nowhere near as big a problem in itself as technical debt and knowledge hoarding are
DeifniteProfessional@reddit
I said this in another comment recently, but we don't have any. Outside of minimal very specific stuff I've made the effort to have written, which largely exist as Word docs within my OneDrive in case I get hit by a bus (or, more likely, quit on the spot), there's nothing. No documentation, no runbooks, no SOPs. We are a team of 4 (well, 3 with someone who handles very very specific onboarding stuff for one department) for far more staff members than a team of 3 should handle. I think I'm the only person who know what an SOP or Runbook is.
It doesn't keep me up at night because I've already mentally quit, but we're way too big of a company for IT systems to be as disorganised, non compliant, and frankly unsecure as they are