Hacker News Reader

Comment by hcarvalhoalves | Hacker News Reader

Another opinion piece, but no data, not even a concrete example.

I get it, every software engineer has strong opinions, but that’s a weak one. If you think writing a lot of code to see what sticks is the job description, you’ll be replaced by GPT in no time - it can do it faster and cheaper. The challenge is always in getting alignment on what should be built, you won’t code your way out of that.

View on HN

Hard agree. I don't know if "design doc" is the right word—I call them technical analyses—but writing up a doc that connects business & product needs to implementation details is highly useful to get everyone on the same page in terms of requirements & deliverables.

If I'm clear on the requirements & everyone else is clear on what I'm delivering, this is unnecessary. Sure, jump straight to prototyping. But this is rarely true for any serious project. There are always unknown unknowns that you need to tease out from the stakeholders, and a technical analysis is a great way to do that.

It's also easier for all involved parties to read, whether they're technical or not, assuming you have some sections that explain things without relying on code.

Yeah 100%. I'm not going to make my product manager read a thousand lines of code just to get them to confirm all the assumptions I made about what they were asking for when I could just clarify.

> If I'm clear on the requirements & everyone else is clear on what I'm delivering.

That's a big 'if', and usually isn't possible without prototyping in my experience. What you're describing seems like something that would be written after a prototype is already done. Presenting a prototype (or iterating on multiple prototypes) is a better way to tease out unknowns than any document.

It's usually not possible without a technical analysis, is my point. A throw-away prototype takes much longer to build and is much harder to review and discuss with stakeholders than a document. Like, how are you going to build a prototype demonstrating design trade-offs—are you just going to build every possible version? Are you really going to make a product manager read a 2000-line PR instead of three pages of bullet points?

Presenting a prototype only really make sense for UI-centric things anyway, and even then, there's a million ways to make a UI mock-up that don't involve functioning code.

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.

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.

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.

Throwaway code is better than a design doc precisely because it is a concrete example.

Without something tangible like code to tether conversations, discussions over abstract designs invariably devolve into "my imaginary piece of string is longer than your imaginary piece of string" arguments that lead nowhere.

It's more likely that someone who holds this belief will be able to move substantially faster with an LLM, than it is that an LLM would take over this task in its entirety.

Sometimes the "data" behind this kind of article can be decades of personal experience.

I think there's merit to both design docs and prototypes.

At the same time, your argument that "you'll be replaced by GPT in no time" is also an opinion that you've not supported with any data; the same thing that you're accusing the OP of.

I mean If I stopped reading opinions, 99% of the HN comments would disappear.

Reply on news.ycombinator.com