4 ms·

I agree you should document the decisions and discussions around them. I never said you shouldn't, just that the discussion shouldn't be entirely written. But y

I agree you should document the decisions and discussions around them. I never said you shouldn't, just that the discussion shouldn't be entirely written. But you can discuss live and summarize the discussion in the doc after. Relatedly, I don't think full discussions about the design doc should live forever in the design doc. When I was at Google, I hated reading design docs where every line had a convoluted, 20-message comment thread attached to it in the margins. When I owned a doc, I'd drive those comment threads to a resolution, write up a concise summary of the debate in the appendix, then resolve the thread.

joshuamorton 1y ago
> Relatedly, I don't think full discussions about the design doc should live forever in the design doc. When I was at Google, I hated reading design docs where every line had a convoluted, 20-message comment thread attached to it in the margins. When I owned a doc, I'd drive those comment threads to a resolution, write up a concise summary of the debate in the appendix, then resolve the thread. Yes exactly, you don't need the entire back-and-forth, but the relevant information should be written down somewhere.