alt Hacker NewsMy problem recently is to have people read design docs I'm writing.
Replies
I think getting people to read design documentation was always the challenge; this is not a new thing.
I've both produced documentation and consumed it. When I consume documentation, I don't expect much. And to be honest, I don't like the low signal to noise ratio in typical design documentation. That was always a problem. Any sufficiently complex thing is just hard into a power point friendly diagram. And anything involving boxes and arrows where the number of boxes is 5 at best, is probably not that interesting to think about.
It certainly feels like this is an intrinsic friction point in a world where more and more of the actual code is written by AI. I know in my workflows, reading a design doc of any length is a big tradeoff of time that could be spent building. Which isn't a new problem to have, of course, but as the time from plan->code->review->deploy keeps racing downward, "reading design docs" feels like it's ripe for disruption as far as how much time and attention it takes.
I found this article posted here a while back insightful: https://refactoringenglish.com/blog/useful-feedback-on-desig...
Start with a single reviewer who is invested in the topic has been helpful for me. Occasionally it is hard to even find one person with how scatter brained everyone seems to have become lately, but depends on who you work with I guess...