Earlier quoted context omitted.
Realistically, i agree with your point and it's probably a good course of action! > Ask, ask, ask. Yes, you can spend days or weeks poring over the code in various ways, but asking those who made it (ideally) or those who maintain it will give you the "why". My question, however, is why aren't these things documented in the first place? In DevTernity (a recent software development conference), the concept of ADRs ( h…
In my experience, many things are documented, but the documentation is unhelpful, redundant or outdated. Sometimes there are several documents on the same thing, some are outdated in different ways, or the author has given up on it. In code itself, often you see comments that say one thing, the function name saying another, and the relationship doing something different. It's probably good company culture for seniors…
> In code itself, often you see comments that say one thing, the function name saying another, and the relationship doing something different.
Is that not a red flag in of itself? Because it seems like at some point someone cared enough to write the docs, but eventually no one cared much to maintain them.
To me, that just expresses that later either the other developers or even that same dev cared only about keeping things running, which was the standard of quality that they chose for themselves, as opposed to actually caring about the long term sustainability and therefore the docs.
I've seen situations like that as well, but generally when everything surrounding the projects is also bad - improper risk management, old dependencies possibly with insecure code, unaddressed technical debt and either god objects or overly long functions with outdated names/docs all go hand in hand.
Personally, i don't take it as "just the way things are" but rather something to be addressed head on - in the past year, i've written everything from onboarding guides to initialization scripts and tooling for around 5-10 projects and have kept them up to date.
Furthermore, i've definitely sent back merge/pull requests on the basis that they need further refinement due to the aforementioned concerns. Not nitpicky stuff that's irrelevant, but rather things that would make the codebase lie to someone reading it, in one way or another.
Of course, one can argue that docs are useless in of themselves because they're not what's actually running on the servers, but personally i disagree with that point of view as well, though perhaps that's a conversation for another day.