I had a situation at work that taught me what I think is a valuable lesson in technical communication.
I was given a small feature to work on, and had a clear idea of how I wanted to implement it. But someone else on the team—let's call them "PM"—had a different idea. PM was dogged in their stance, and since they had seniority, their opinion carried more weight. No matter what I said, I could not get them to see things my way. So I gave up.
I was asked to write an implementation plan based on PM's idea. While writing the document I discovered that PM's idea did not align with our current postmortem process. At the same time my idea also had a flaw: it wouldn't work in an important edge case.
We were both confidently wrong. The correct approach was actually a third option brought up while discussing the document with a colleague.
I have always known that design docs are useful, especially for complex features. But this is my first time seeing them as a tool for resolving arguments, regardless of feature size.