top | item 42428127

(no title)

mghfreud | 1 year ago

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.

discuss

order

kccqzy|1 year ago

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.

digging|1 year ago

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.