2 ms·

I found using "architectural decision records" to be helpful; it's not a panacea and I'm sure there's other approaches, but the gist of it is that you make a do

I found using "architectural decision records" to be helpful; it's not a panacea and I'm sure there's other approaches, but the gist of it is that you make a document, write down your thought processes, consider the different options (demonstrate you did your homework), and get the team together to proverbially shake hands on it. It's not set in stone; if anything, the writing reflects "what we know right now" about a problem and its possible solutions, but it's a message to the future when either the context of the problem changes, the problem is better understood, the underlying assumptions and/or requirements change, or something changes in the solution. It's both committing to a thing "in the moment", while leaving it open for updating down the line. It's much preferable to someone just picking something because of gut feeling / hype / assertiveness / cool factor which is how a lot of projects end up in the bin after a few years.

RHSeeger 2y ago
I tend to do something like this for most tickets I work on (that have choices to be made). I work through all the details and make sure I understand them all, then note what the difference choices are for various things. Where there's a choice to be made that requires "customer" input but that I have a pretty solid idea what the right choice is so am going to move forward on that, I'll make note of it, etc. It also gives me time/space to document ambiguities in the requirements. I am.. overly verbose in tickets. That being said, it's come in handy many times in the past; some of which are me trying to figure out why I made a specific choice.
- simonw 2y ago
  "I am.. overly verbose in tickets." So am I, and I'm proud of it. I see a GitHub issue thread as effectively infinite storage for the ideas, decisions and research behind a change I make to a codebase. Here's a recent example - 51 comments and they were almost all me talking to myself https://github.com/simonw/llm/issues/617 https://github.com/simonw/llm/issues/617

RHSeeger 2y ago

I tend to do something like this for most tickets I work on (that have choices to be made). I work through all the details and make sure I understand them all, then note what the difference choices are for various things. Where there's a choice to be made that requires "customer" input but that I have a pretty solid idea what the right choice is so am going to move forward on that, I'll make note of it, etc. It also gives me time/space to document ambiguities in the requirements. I am.. overly verbose in tickets. That being said, it's come in handy many times in the past; some of which are me trying to figure out why I made a specific choice.

simonw 2y ago
"I am.. overly verbose in tickets." So am I, and I'm proud of it. I see a GitHub issue thread as effectively infinite storage for the ideas, decisions and research behind a change I make to a codebase. Here's a recent example - 51 comments and they were almost all me talking to myself https://github.com/simonw/llm/issues/617 https://github.com/simonw/llm/issues/617