[KronisLV]

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 (https://adr.github.io/) was discussed. To me, it made a lot of sense: the code is the implementation, whereas a bunch of Markdown files can explain the "why" behind it, as well as all of the stuff that wouldn't appear in Jira or regular code comments or wherever.

After all, not every senior dev has that many hours to spend onboarding new team members, nor are their memories also that good to remember everything.

[muzani]

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 to just accept that the new guy will be a productivity sink for a while. Get them up to par quickly so they'll be productive earlier. Knowledge is like compound interest, it's easier to start them out with a lot and then have them figure it out rather than have them figure it out from the start and ask if stuck.

[larsrc]

A neat trick is to have the new person update the docs whenever they needed to ask a question.

Writing docs falls in the realm of error handling and testing. Lots of developers only want to deal with the happy path not those extra drags. Standard CS education isn't helping here.

[KronisLV]

> 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.

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.