Re:Code speaks louder than design docs
by dijksterhuis on Monday December 16, 2024 @03:54AM
(#42429213)
i originally wanted to comment on this to disagree with you. then i sat and read your comment in full and realised i agree with you.
with a weird caveat …
if you don’t have an audience who is willing to read what you’ve edited, editing can be a partially pointless excercise.
last shop i was in i’d edit this stuff to glorious beauty. no-one else would ever read it. i tried presentations instead. didn’t help. i tried live sharing the doc in a meeting, no one cared.
but editing a design doc (or a big PR description or whatever) is always helpful for me as it is a process where i’m editing the problem/solution description without having to move code around.
i’ve done a few good refactors off the back of editing some text/diagrams.
lesson i learned: edit design stuff as if someone else will read it, but do the editing for myself (to learn something or clarify something about the problem/solution).
with a weird caveat …
if you don’t have an audience who is willing to read what you’ve edited, editing can be a partially pointless excercise.
last shop i was in i’d edit this stuff to glorious beauty. no-one else would ever read it. i tried presentations instead. didn’t help. i tried live sharing the doc in a meeting, no one cared.
but editing a design doc (or a big PR description or whatever) is always helpful for me as it is a process where i’m editing the problem/solution description without having to move code around.
i’ve done a few good refactors off the back of editing some text/diagrams.
lesson i learned: edit design stuff as if someone else will read it, but do the editing for myself (to learn something or clarify something about the problem/solution).