The worst development situation I ever stepped into was an IT department where the five year old production code was completely documented. Literally NO documentation.
Our team of three all joined within two months of each other after the entire previous IT department left the company. We had to document the system via debugging production bugs and tracing through code manually because there were no unit or integration tests to work with.
It reminds me of a tweet from Leon Bambrick:
Newbie: Ok great, can you shoot me a link to the documentation?
— Leon Bambrick (@secretGeek) May 3, 2017
Oldie: Errr... we have more of a... rich oral tradition.
At the other end of the spectrum are the first-class development teams, who not only have tests and documentation, but even go beyond the “how” the code works and document the “why”.
Documenting the “why” - why decisions were made at the time - gives context to anyone joining the team and even helps the existing team remember why the choice was made.
These decision records should be short and kept as close to the codebase as possible to improve the chances they get read.
What should an ADR contain?
Title
Titles should be as descriptive as possible and include a number to keep records in a general order as the decisions were made. It also makes it easier to refer back to previous decisions.
Context
The context section covers the situation “on the ground” around which the decision was made.
Decision
What was the ultimate decision that was made.
Status
The status for a record can be accepted, or it could be superseded if another decision in the future reverses this particular decision.
Consequences
The consequence section outlines what the results are after the decision has been made. These can be positive, neutral or negative.
More about ADRs: https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions