News for hackers. Stuff that matters.
Re:Code speaks louder than design docs by mghfreud on Sunday December 15, 2024 @11:59PM (#42428127)
Why not get it read by a couple peers and iterate on their feedback? My writing is not great, but with the design docs I created, the first version is always terrible, not easily understandable mostly because of not listing all the assumptions whereas the third version almost always becomes something I would never be able to achieve myself. Over the years, I settled on 2 rounds of review. First to mostly add missing sections and rearchitect the design and the doc, second to mostly hone the explanation/details.
Re:Code speaks louder than design docs by kccqzy on Monday December 16, 2024 @10:05AM (#42431640)
You have nice coworkers willing to read drafts. If your coworkers are busier (if they are more senior) they might not. Or they might read half a page and then stop because there isn't enough context and background information in the doc. Or they might read something and misunderstand it because of bad writing. I'm usually not the kind to waste other people's time like that.
Re:Code speaks louder than design docs by digging on Monday December 16, 2024 @12:07PM (#42432942)
Or, they won't say anything about it at all, because they (choose all that apply):

a) are not good communicators,

b) do not respect you,

c) are afraid to admit they don't understand (even if your doc is clearly shit),

d) do not care very much about the project.

Re:Code speaks louder than design docs by ChrisMarshallNY on Monday December 16, 2024 @12:21PM (#42433085)
In my experience, it’s usually (d), even if they are on the team.