[al_borland]

If it’s something in the code, that’s where I use comments. It’s the only place people have a chance of seeing it. Even when I add these comments some people ask me about the code instead of reading them. This isn’t just for others, I forget as well. Something to the effect of…

# This previously used ${old-solution}, but has moved to ${new-solution} because ${reason}

Or

# This is ugly and doesn’t make sense, but ${clean-logocal-way} doesn’t work due to ${reason}. If you change ${x} it will break.

Or

# This was a requirement from ${person} on ${date}. We want to remove this, but will need to wait until ${person} no longer needs it or leaves the company.

[zain__t]

Those comment templates are actually really well structured you've invented a mini decision record format without calling it that. The problem you're hitting is discoverability the why is there, but only if you happen to read that exact line. What if a new dev could ask 'why does this auth flow work this way?' and your comment was part of the synthesized answer along with the PR, the Slack thread, and the ticket that created it?

[al_borland]

Most people where I work use Confluence for the overarching architecture decisions, but that also has a massive discovery issue.

If there is a Confluence doc that relates to my code, I will usually cross reference it. The Confluence link goes at the top of the file, and a link to the repo goes into Confluence. Even with this, the discovery problem remains, as one of those things needs to be found.

Using chat is a non-starter, as our chats are purged after 6 or 12 months. PRs also seem like a very challenging place to keep the information without a lot of systems in place and strict adherence.

Tickets can work, until the ticketing system changes. I’ve been through 3 ITSM platform changes and 3 changes in agile software. Old information is lost in these transitions as it’s usually only in-flight stuff that migrates. Confluence will meet the same fate soon I’m sure.

At the end of the day, the code is the only thing I can trust to be there. Once the code is gone the information matters less. I also try to be pretty diligent about readme files can get pretty wordy. Adding some kind of architecture doc into the repo might be another option, similar to what claude.md has become for a lot of people. I actually might do this for a project I’m starting now, as it’s pretty confusing… though I’m hoping I can come up with a way to make it less confusing.

[4b11b4]

Putting decision inside the code is interesting... but scattered. Some decisions are made way higher up and implicitly touch many places

[al_borland]

Yeah, this doesn’t solve the “why Redis” problem. What I’m most concerned about with this is stopping someone who might be trying to update the code in the future (including me) from going down a rabbit hole I’ve already been down.

[4b11b4]

Yeah that's the point of being able to revisit past ADRs easily. Will have demo soon