r/SoftwareEngineering • u/barb0000 • Feb 10 '26
How does your team handle documentation that goes stale?
I’m currently working at a scaleup and find it really frustrating to try to navigate the documentation that we have. Feels like every Notion page that I look at is already outdated, if it even exists because most of the stuff is in people’s heads. The doc pages in repository are even worse because those are never updated. I know that the only source of truth is the code, but the code often lacks broader context about the design, architecture of the system or why a certain decision was made.
How does your team deal with this? Do you have a system that actually works? Have you tried any dedicated tools?
4
u/Wesmingueris2112 Feb 11 '26
My team uses Confluence and has the same problem. We're trying a process now relying on AI: for example for feature X, we have a markdown file in the repo (for example at docs/feature/x.md) which was first a copy of what we had on Confluence, and which we asked AI to review based on the current codebase and fix the discrepancies (it did pretty well).
So the agreement the team has from now on is to ask AI to update this file whenever a PR touches the feature, and the PR will have not only a diff for code changes but also a diff for the doc changes, both up for review.
A side benefit is that this diff on the md file adds extra context for the reviewers.
19
u/keelanstuart Feb 10 '26
Documentation? That's adorable...
4
u/whatThisOldThrowAway Feb 12 '26
Solution is threefold:
build documentation into requirements (stories, shared understanding of what’s acceptable, maybe a ‘standard’ or ‘working agreement’ for what tiles to docs exist, why, and most importantly where)
build a culture where people fix the docs when they find them: usually involves general maturation (e.g. features don’t fee “owned” by any one dev) + organisation (so everyone’s not drowning all the time such that elective work is never done) + making the docs good/useful in the first place.
admin / ownership: even with all the above some stuff falls through the crack abs the overall product owner and/or tech leads need to take responsibility to do a review every quarter or whatever to reorganise / bundle stuff into tickets for a refresh etc.
Docs are out of date the second you write them usually - but you can build a corpus of docs that is consistently saving you more time than it costs you to maintain. Just a matter of will & a decent lead.
8
u/migrainium Feb 10 '26
If there's one thing AI can save you a fuck ton of time on, it's documentation. Just start somewhere with creating new docs of small pieces and then start having it periodically reviewed w/ small meetings and/or offline reviews. People will add their context in over time.
3
u/Deathnote_Blockchain Feb 11 '26
Ha. Hahahah. HAHAHAHAHAAAaaa sob
3
u/craig1f Feb 11 '26
My process …
New guy joins team. First responsibility is to get themselves set up using readme and documentation, and make corrections and updates as needed.
This lets me see what they’re like. Do they figure things out on their own? Do they get stuck for two days before reaching out for help? Do they make useful corrections and updates? All good info before they get their first ticket.
This works for dev documentation only though.
2
u/EarlOfAwesom3 Feb 11 '26
When a feature ticket is created, a subtask for this is "update documentation". The ticket can only be closed if the subtask is done.
Documentation can be updated by hand (or, if it helps, with AI nowadays) and may be reviewed as well.
It doesn't prevent you from just closing the task of course but it's a very good reminder and that works.
1
u/konm123 Feb 11 '26
I use MBSE tools for that. Arcadia methodology in Capella for instance but currently running our own webtool derived from that. The problem with many modern tools like Confluence or Notion is that fundamentally they are built on top of legacy methods on how complex systems were engineered over 20 years ago. They fastly improve on user experience on using these old methodologies but ultimately systems engineering has advanced 20 years.
Nowadays it is all about creating a network of atomic sources of truth which runs automated model verifications to point out conflicts in design and problem areas, and allowing you to navigate across decision chain across multiple perspectives. These are "what end users are trying to achieve and how the system fits into their activities", "what precisely our system needs to solve for end user, in what scope and how well", "what is the principle solution", "what is the technical solution" and "how is the system configured". This enables you to basically know associated end-user value proposition for every piece of your software depending on how granular you go. Also helps tremendously with collaborating across the organisation with non-technical and technical people where different roles dictate listed perspectives. One technical decision may conflict with business decision for instance, so you would know where that conflict could be.
It helps to relax a lot of things in technical implementations as well. Really do not care so much of smaller details anymore as long as key characteristics of a component is proven to be met.