News for hackers. Stuff that matters.
Re:Code speaks louder than design docs by softwaredoug on Sunday December 15, 2024 @02:35PM (#42425427)
That’s exactly my point, I think you get better alignment with “show don’t tell”.

Rectangles and dotted lines only get you so far. Being removed from actual code makes you forget the real constraints - the stuff that actually slows you down doesnt appear in google docs. “Here’s what I’m thinking (points at Draft PR)” gets you farther in my experiencre.

And yes it’s 100% an opinion. It’s a personal blog not a peer reviewed article :) I’m happy to be wrong.

Re:Code speaks louder than design docs by Arainach on Sunday December 15, 2024 @03:18PM (#42425682)
Design docs are much easier to be reviewed. Throwaway code/a prototype is a huge amount of content where it's easy to miss things.

When I go back to understand a component, I want to know why the decisions were made. A well written doc illustrates exactly that - here are the options considered, here is why we chose this option to be implemented. It can be quickly read and searched.

Throwaway code - even a pull request with comments - is not the same. It takes much longer to process, much longer to review, and it's easy to miss seemingly obvious things because the important bits are surrounded by a bunch of unimportant boilerplate.

Put another way: anything that could be represented by a single PR is generally not significant enough to need a design document. Anything significant enough to need a design document should be a chain of smaller PRs / commits which allow the pieces to be reviewed thoroughly by themselves and have tests to show that they each work.

Re:Code speaks louder than design docs by hcarvalhoalves on Sunday December 15, 2024 @09:08PM (#42427404)
I guess this varies largely with project, stakeholder, etc. The kinds of projects I have been involved, showing a PR would’ve been either useless to communicate anything, or have to explain why it’s “throw away” and why we can’t ship the prototype.

That’s why I stressed it’s an opinion piece but no data. Unfortunately in this industry we have a lot of experience reports, but lack actual data on what is or isn’t more effective way to work.