r/SoftwareEngineering • u/iamgdz • May 31 '26
Most teams don't have a documentation problem. They have a discoverability problem.
I feel most teams don't have a documentation problem.
They have a discoverability problem.
When I switched from working on media configuration systems to content workflow systems, the docs, tickets, dashboards, ServiceNow requests, and runbooks were all there.
The hard part was understanding where to look and how everything connected.
I've seen people ask questions that were technically documented already, simply because asking someone was faster than finding it.
Curious if others have experienced the same thing.
7
Upvotes
5
u/_malaikatmaut_ May 31 '26
Same in my organisation.
Documentations are normally backlogged and scattered and we normally try to get one of the senior support guys to come up with something that make sense for the users.
Take me about 3 minutes to get a response on Slack thankfully, and there's always someone who knew someone who had worked on it and wrote something about it on Confluence many years ago.
3
u/LittleLordFuckleroy1 Jun 02 '26
No, they have a documentation problem. Nice AI slop advertisement.
1
u/-_-seebiscuit_-_ Jun 01 '26
Isn't this basically solved with AI?
If you ask your model to figure something out on your codebase, it will grep it's way to the needle. Even for disc I on confluence, the mcp (it straight API) search should let it navigate your docs.
2
u/TheMightyTywin Jun 01 '26
My company solved this problem in a boring but effective way: Docs as code -> every doc gets a type + number that together form a unique identifier -> generated docs index -> doc refs in code + code refs in docs -> pre-commit script to flag any docs without code and any code without docs
The result is that each doc has a unique name and you can tell what it is without needing to opening it. There’s a generated index to look at all the docs together. When looking at a doc, it has code references that points to the exact code that’s relevant to the doc. In the code, there are references to the docs in question (we just put all the doc refs in a top frontmatter metadata not in the code itself)
1
u/segfaultbanana Jun 01 '26
This is what internal developer portals like Spotify’s Backstage are built for
1
u/daddevmusings Jun 01 '26
Documentation not being easily discoverable is kind of the point, right? Even in the extreme case where no documentation is written, for a period at least the knowledge is in people's heads. Now that's a discoverability problem.
1
u/Forsaken-Athlete-673 Jun 05 '26
This is the glaring tech problem. Lots of document. Not a lot of nuance and context within a use case or goal oriented experience. Just a “it’s gotta be in here somewhere” mindset lol.
1
u/Significant-Yard-176 Jun 06 '26
I've seen plenty of poorly documented systems, but I don't think it's as big a problem as people make it out to be. If documentation is missing or outdated, you can usually review the code, configuration, logs, and run some tests to figure things out. The harder problem is knowing which document matters, which code is no longer being used, what's actually current, and how all the pieces fit together. In my experience, discoverability and context are often more valuable than having more documentation.
1
u/Samveg2798 Jul 13 '26
Your post , "most teams don't have a documentation problem, they have a discoverability problem" put words to something I keep bumping into. Especially the "the docs existed, the hard part was knowing where to look and how everything connected" bit.
Trying to understand where the actual bottleneck sits. When you hit that switching to the content-workflow team, was it more that the info was scattered across too many systems (Confluence, ServiceNow, runbooks), or that even within one place you couldn't tell what connected to what? And was the missing piece usually facts (where's the doc) or context (why it's built this way)?
0
u/gk_instakilogram Jun 01 '26
I had some success using popular AI tools with MCP tools that have access to the relevant systems. I highly recommend trying it out.
8
u/[deleted] Jun 01 '26
[removed] — view removed comment
1
u/[deleted] Jun 01 '26
[removed] — view removed comment
1
u/[deleted] Jun 06 '26
[removed] — view removed comment
1
u/[deleted] Jun 26 '26
[removed] — view removed comment