This is called prototyping, which is a valuable part of the design process; some people call it "pathfinding".
These are all inputs into the design. But a design is still needed, of the appropriate size, otherwise you're just making things up as you go. You need to define the problem your are solving and what that solution is. Sometimes that's a 1-page doc without a formal review, sometimes it's many more pages with weeks of reviews and iterations with feedback.
Don't forget: "weeks of coding can save hours of planning" ;)
> a design is still needed, of the appropriate size, otherwise you're just making things up as you go.
A design needs to be understood, certainly, but that doesn't necessarily mean a document, or indeed any permanent artifact. And if you do need a permanent record, a PR can be as good a medium as any.
> Don't forget: "weeks of coding can save hours of planning" ;)
I've found the opposite is true far more often. People plan and plan until the plan is not merely pointless but actively destructive to productivity.
Back in ye olde times a half hour or so with a chalk board and some smart people, go away try some things then come back and erase / write some more worked pretty well.
I think that it’s one of those dichotomies. One needs both a design and a prototype.
As you say, weeks of coding can save hours of planning. But weeks of planning can be wasted, too. It’s easy to write things on paper which don’t make sense or are impossible, e.g. ‘We will colour the unicorn fleet semi-sad.’ Ideally, the design and the prototype would evolve in concert, each iteration of one driving the next iteration of the other, spiralling like the double-helix of DNA.
The great virtue of a bias towards building prototypes is that at the end of a round of prototyping one actually has software which can do something — at the end of a round of design one doesn’t really have anything.
Agreed, why not both? In fact, I’d say, first write up a theory, then demonstrate that it does or does not work using a prototype, then write the actual design doc. At all times, and continuing into the implementation phase, prioritize the disposability of your code. The easier it is to delete, the better.
I think my argument would be that they could be the same artifact. Hence my usage of Draft PRs with a lot of rich documentation. And a willingness to throw it all away if you don't think its ultimately the right approach.
The real problem is the industry's inability to throwaway first solutions, so we introduce this (IMO inefficient) 'design doc' step as a safety mechanism
Very interesting! Is "tree-house building" a reference to something specific or did you make it up? It strikes me that engineering is either a spectrum, or it's a segment of a larger spectrum (the name of which I don't know). Tree-housing is near one end of that spectrum, the MacGyver end, and dam-building is near the other end (where the problem is thoroughly researched, the goals are calculated, and the designs are all made to serve those calculations specifically).
Do you feel "engineering" could cover the entire spectrum, where your "Engineering" specifies everything on one side of "has a design doc"? If not, is there a name for the whole spectrum? Does crocheting from a pattern sit anywhere on this spectrum, or is it something else, or does it mean that my spectrum-of-engineering is an illusion? Open questions here, not directed at DrNosferatu necessarily.
Writing is really beneficial for exploring the problem space.
Many times I’ve confidently thought I understood a problem, started writing about it, and come away with new critical questions. These things are typically more visible from the abstract, or might not become apparent in the first few release milestones of work.
I’m reminded of a mentor in my career, who had designed an active/active setup retroactively for a payment gateway. He pulls up a Lucidchart and says “this diagram represents 6 months of my life”.
They’re not always necessary or helpful. But when they are you can save weeks of coding with a few days of planning.
I had a boss who had a math degree. He'd map out the flow from start to finish on a whiteboard like you see mathematicians on TV/movies. Always had the smoothest projects because he could foresee problems way in advance. If there was a problem or uncertainty identified, we'd just model that part. Then go back to whiteboard and continue.
An analogy is planning a road trip with a map. The way design docs most are built now, it shows the path and you start driving. Whereas my bosses whiteboard maps "over-planned" where you'd stop for fuel, attraction hours, docs required to cross border, budget $ for everything, emergency kit, Plan A, Plan B.
Super tedious, but way better than using throwaway code. Not over-planning feels lazy to me now
Sure, everyone has a plan until you get punched in the mouth; however, that saying applies to war, politics, negotiations, but not coding.
I the book How Big Things Get Done they analyze big and small project failures and success and end up with something along the lines:
1. Spend as much time in planning as necessary, in the context of mega projects planning is essentially free, maximize the time and value gained in planning.
2. Once you start execution of the plan, move as fast as possible to reduce likelihood of unforeseen events and also reduce costs increases due to inflation, interest paid on capital etc.
Yes I have to second that. MLJ.jl is also written by a mathematician and the API is excellent. Truly well thought-out.
(If you think “why does MLJ.jl have so few stars?” please keep in mind that this library was written for the Julia language and not for Python. I honestly don’t think the library is the cause of low popularity. Just wrong place wrong time.)
> however, that saying applies to war, politics, negotiations
It’s not even an argument against planning. You’d be a fool to go to war without a plan. The point of the saying is that you’d be a fool not to tear up your plan and start improvising as soon as it stops working.
I had to do this for a patent application, and likewise found it very useful for identifying holes in my thought process or simply forcing myself to do the functional design work up-front and completely.
It was also great for brainstorming about every feature and functional aspect you can imagine for your product, and making an effort to accommodate it in your design even if it's not MVP material.
In my experience it applies to coding when you have any reliance on third party libraries or services and don't have an extensive amount of actual real world experience with that technology already.
I agree writing is beneficial. But I also find this works with coding. And they go hand in hand for exploring in my experience.
And in the end a good PR has a lot of writing too and has this effect. IMO this sort of well documented draft PR serves as a better design proposal because pure writing causes you to forget important constraints you only remember when you’re in the code.
Agreed. You can write prose or implementations or tests beforehand and I don't think it matters too much which you choose, just as long as you give yourself a phase 2 for incorporating the learning you did in phase 1 and put a reality check of some kind in between them.
The only problem with having the draft being implementation is that maybe you'll get pressured into shipping the draft.
The biggest issue that I’ve had with design docs, is that nobody reads them; even if required by their employer.
The biggest issue that I’ve had with prototyping, is that people consider it “ship” code, and force me to use it as final code.
I find that I’m best served with a hybrid approach, where I spend a lot of time planning and documenting, but basically, for myself, then writing ship-Quality prototype code, so that using it in the end product is OK.
The reason people don't like to read the average design doc is because the average software engineer doesn't have enough writing skills to express the concept clearly and concisely without editing. The design doc becomes a mumble jumble of raw notes that nobody really understands except the author. And then people dread reading this kind of raw notes.
However, if someone tells that design doc writer that this is something like a term paper at school that is being graded, they can actually improve their writing by quite a bit by doing some editing. So the symptom is really the same as prototyping: people write draft-quality design docs and magically hope it to be a good quality piece of writing suitable for a wider audience. What they need is a few rounds of editing, just like when they write prototype code they need a few rounds of refactoring.
As much as I get frustrated with GPT4's limitations when it comes to code, it's quite good at expanding detailed bullet points into solid design prose.
You still have to read it back and triple check it, as you would your own work, but you don't need all the time it takes to extensively expand it from draft.
Also, which it is in context it's quite good at documenting what needs to be done to test it.
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).
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.
Add to that engineers that don’t like/aren’t good at reading (at least in my time Zone) and you end up with people asking for stuff that is documented or even understanding the complete opposite of what was written.
We had to build and launch something by a deadline in order to avoid renewing a contract that would have cost $x mil. But we discovered we weren't going to finish in time with the resources and the approach that was planned.
So I got approval to hack out a temporary impartial suboptimal version and we were able to take off in time.
This has allowed us to fly for a bit while others finish building out the permanent proper version of that part of the wing.
In fact, during our flight we discovered missed requirements in the original design. This has delayed that proper version's release to prod. But I've been able to add that quickly to my hack and keep us flying.
My hack doubles as a production support tool. And as an alternate route if the permanent version needs to be paused because of a bug. Yes it's a partial imperfect hack but it has benefits.
Someone has complained about the language I used since it is less common. But remember, we weren't going to be able to take flight with the existing resources and approach.
We would have needed more and/or faster developers in the favored language to meet the deadline.
If any present employee (including me) had bandwidth and was able to be as productive in the favored language as I was building my hack in the uncommon language, that employee would have been tasked to build the permanent solution on time. That option was not available.
Anyways, if you have an existing production support tool, it's also a place where prototype features can live for a while.
I think it's not uncommon for a dev to be faster with one language than another. And for another dev to know the same two languages but be more productive in the opposite direction. (And I am mindful that the bar was much lower for me -- being a temporary hack, my stuff didn't have to integrate fully or have the same level of production manners)
But here are two factors that make me faster in the uncommon language.
You know the usual debugger experience where if you keep stepping or you set a breakpoint and then later realize the interesting part is actually behind you? Which means you have to start your scenario again?
Well, the uncommon language has a recording debugger so you can visit any points in front of or behind you, and see what any variable or return value was. You're not limited by the current stack because the recorder captured every package you told it to from the beginning
Even a third party package...
This means I only have to debug once to find the bug, not n times.
And the language is expressive and pliable enough that this debugger was implemented in the language itself...
And mostly by one guy -- not me of course -- it didn't take a whole company to implement it.
And you know how in some languages like Java if your car (program) starts acting up in LA, you have to update the blueprint, send it to the car factory, build the new car, drive it back to LA, and try the same left turn to see it it still ferks?
With the uncommon language, I can stay in LA and change the car while the engine is still running, n times before the 2nd Java car arrives. The language is Clojure.
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.
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.
> 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 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.
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.
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.
In my experience there is a MASSIVE difference in the type of feedback someone gives on code vs a design. A design doc encourages "why" questions to get everyone thinking about the problem space. For example, a design doc comment might be "why are we suggesting a Rust Webserver when nobody in the company is proficient in Rust yet?".
In my experience those more subtle questions are much harder to raise once a prototype is working - "why does the team's experience matter? look how great it works! If you don't block it we could get this to production in a week by just polishing the prototype!"
This is not neccesarily a bad thing though. Lots of "why" questions are really counterproductive bikeshedding. Especially when it comes from just reviewing a design as opposed to working code.
We imagine software efforts that go through a clean, neat flow:
We write a design doc. Then make small incremental changes in a PR to rollout the functionality. Our git histories look clean and orderly. Like a steady march of progress.
Who imagines this? Professors who teach software engineering classes?
This reminds me of people who think that you write prose (essays, stories, novels, etc) by writing an outline and then "filling it out" with prose, as if in the process you will never discover anything that requires you to rewrite or restructure the document. Nobody writes that way. First drafts are always terrible and basically all good writing has been heavily revised.
Writing code is much more like writing than it is like building a house or a bridge.
For myself, I always find great value in debugging new code that I have written. Something about stepping line by line through new logic, and viewing variables/memory really helps me to improve my code. "Oh, I don't need that local var." "Oh, I should add a temp var to make the code easier to debug here." "Oh, this code is weird when the collection that we iterate is empty." No matter how old I get, and no matter how much code I write, I always discover new things when I debug my newly written code. I guess this could be compared to an author writing a first draft, then going back to read it... or reading it aloud to themself or another person.
I really like this process: using an ongoing comment thread to document design decisions along the way, as opposed to trying to formalize them in a single document.
I use GitHub issues for this myself but that's functionally equivalent to using a PR - a PR is effectively a GitHub issue with an attached branch of code.
But then how do you communicate the latest consensus on all issues, e.g. for a newcomer who doesn't want to slog through months of communication, or a team member who has been part of the thread all along but can't easily find where the team agreed on a particular thing? In other words, how do you summarize the thread into final documentation?
The documentation that needs to be kept 100% up-to-date is the usage documentation. Here's how to use this Python class library. Here's how to use this REST API. Here's how to use this CLI tool.
THAT should live in the same repository as the code itself, and updates to it should be enforced as part of code review.
Design documentation that describes the process that got to that point should live separately from the repo in something like GitHub Issues, because it's not guaranteed to be up-to-date but can still be referenced during code archaeology sessions when trying to figure out WHY the software is the way it is.
Commit messages work too, but I prefer to have a short commit that links to an issue thread where I can find out more.
Well unfortunately there’s never “final” design documentation. Design docs go out of date pretty fast.
I think it’s healthy to treat design docs like a historical artifact - true at one point in time. It’s less likely they stay up to date to reflect reality.
Readit News
These are all inputs into the design. But a design is still needed, of the appropriate size, otherwise you're just making things up as you go. You need to define the problem your are solving and what that solution is. Sometimes that's a 1-page doc without a formal review, sometimes it's many more pages with weeks of reviews and iterations with feedback.
Don't forget: "weeks of coding can save hours of planning" ;)
A design needs to be understood, certainly, but that doesn't necessarily mean a document, or indeed any permanent artifact. And if you do need a permanent record, a PR can be as good a medium as any.
> Don't forget: "weeks of coding can save hours of planning" ;)
I've found the opposite is true far more often. People plan and plan until the plan is not merely pointless but actively destructive to productivity.
As you say, weeks of coding can save hours of planning. But weeks of planning can be wasted, too. It’s easy to write things on paper which don’t make sense or are impossible, e.g. ‘We will colour the unicorn fleet semi-sad.’ Ideally, the design and the prototype would evolve in concert, each iteration of one driving the next iteration of the other, spiralling like the double-helix of DNA.
The great virtue of a bias towards building prototypes is that at the end of a round of prototyping one actually has software which can do something — at the end of a round of design one doesn’t really have anything.
The real problem is the industry's inability to throwaway first solutions, so we introduce this (IMO inefficient) 'design doc' step as a safety mechanism
Prototyping and pathfinding are totally fine and mostly necessary.
*But*, Software Engineering without design docs or any kind of specification (even if succinct) is just tree-house building, *not* Engineering.
And the bigger the size and importance of the project, the sooner the problems and technical debt will start to show.
Do you feel "engineering" could cover the entire spectrum, where your "Engineering" specifies everything on one side of "has a design doc"? If not, is there a name for the whole spectrum? Does crocheting from a pattern sit anywhere on this spectrum, or is it something else, or does it mean that my spectrum-of-engineering is an illusion? Open questions here, not directed at DrNosferatu necessarily.
Deleted Comment
Also, "weeks of planning can save hours of coding" :)
Many times I’ve confidently thought I understood a problem, started writing about it, and come away with new critical questions. These things are typically more visible from the abstract, or might not become apparent in the first few release milestones of work.
I’m reminded of a mentor in my career, who had designed an active/active setup retroactively for a payment gateway. He pulls up a Lucidchart and says “this diagram represents 6 months of my life”.
They’re not always necessary or helpful. But when they are you can save weeks of coding with a few days of planning.
An analogy is planning a road trip with a map. The way design docs most are built now, it shows the path and you start driving. Whereas my bosses whiteboard maps "over-planned" where you'd stop for fuel, attraction hours, docs required to cross border, budget $ for everything, emergency kit, Plan A, Plan B.
Super tedious, but way better than using throwaway code. Not over-planning feels lazy to me now
Sure, everyone has a plan until you get punched in the mouth; however, that saying applies to war, politics, negotiations, but not coding.
1. Spend as much time in planning as necessary, in the context of mega projects planning is essentially free, maximize the time and value gained in planning.
2. Once you start execution of the plan, move as fast as possible to reduce likelihood of unforeseen events and also reduce costs increases due to inflation, interest paid on capital etc.
[0] https://www.goodreads.com/book/show/61327449-how-big-things-...
(If you think “why does MLJ.jl have so few stars?” please keep in mind that this library was written for the Julia language and not for Python. I honestly don’t think the library is the cause of low popularity. Just wrong place wrong time.)
That’s a bit uncharitable but following this line of thought - you also need those smart people to be confident and communicative.
It’s not even an argument against planning. You’d be a fool to go to war without a plan. The point of the saying is that you’d be a fool not to tear up your plan and start improvising as soon as it stops working.
It was also great for brainstorming about every feature and functional aspect you can imagine for your product, and making an effort to accommodate it in your design even if it's not MVP material.
In my experience it applies to coding when you have any reliance on third party libraries or services and don't have an extensive amount of actual real world experience with that technology already.
hey, the EU just introduced this new regulation is the software version of getting punched in the mouth.
How was it better? I think a lot of people plan precisely because it feels virtuous, but that's true regardless of whether it's effective or not.
Certain projects have too many unknowns to overplan and you need to collect data to construct the assumptions necessary to evaluate the approach.
And in the end a good PR has a lot of writing too and has this effect. IMO this sort of well documented draft PR serves as a better design proposal because pure writing causes you to forget important constraints you only remember when you’re in the code.
The only problem with having the draft being implementation is that maybe you'll get pressured into shipping the draft.
The biggest issue that I’ve had with prototyping, is that people consider it “ship” code, and force me to use it as final code.
I find that I’m best served with a hybrid approach, where I spend a lot of time planning and documenting, but basically, for myself, then writing ship-Quality prototype code, so that using it in the end product is OK.
However, if someone tells that design doc writer that this is something like a term paper at school that is being graded, they can actually improve their writing by quite a bit by doing some editing. So the symptom is really the same as prototyping: people write draft-quality design docs and magically hope it to be a good quality piece of writing suitable for a wider audience. What they need is a few rounds of editing, just like when they write prototype code they need a few rounds of refactoring.
You still have to read it back and triple check it, as you would your own work, but you don't need all the time it takes to extensively expand it from draft.
Also, which it is in context it's quite good at documenting what needs to be done to test it.
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).
So I got approval to hack out a temporary impartial suboptimal version and we were able to take off in time.
This has allowed us to fly for a bit while others finish building out the permanent proper version of that part of the wing.
In fact, during our flight we discovered missed requirements in the original design. This has delayed that proper version's release to prod. But I've been able to add that quickly to my hack and keep us flying.
My hack doubles as a production support tool. And as an alternate route if the permanent version needs to be paused because of a bug. Yes it's a partial imperfect hack but it has benefits.
Someone has complained about the language I used since it is less common. But remember, we weren't going to be able to take flight with the existing resources and approach.
We would have needed more and/or faster developers in the favored language to meet the deadline.
If any present employee (including me) had bandwidth and was able to be as productive in the favored language as I was building my hack in the uncommon language, that employee would have been tasked to build the permanent solution on time. That option was not available.
Anyways, if you have an existing production support tool, it's also a place where prototype features can live for a while.
But here are two factors that make me faster in the uncommon language.
You know the usual debugger experience where if you keep stepping or you set a breakpoint and then later realize the interesting part is actually behind you? Which means you have to start your scenario again?
Well, the uncommon language has a recording debugger so you can visit any points in front of or behind you, and see what any variable or return value was. You're not limited by the current stack because the recorder captured every package you told it to from the beginning
Even a third party package...
This means I only have to debug once to find the bug, not n times.
And the language is expressive and pliable enough that this debugger was implemented in the language itself...
And mostly by one guy -- not me of course -- it didn't take a whole company to implement it.
And you know how in some languages like Java if your car (program) starts acting up in LA, you have to update the blueprint, send it to the car factory, build the new car, drive it back to LA, and try the same left turn to see it it still ferks?
With the uncommon language, I can stay in LA and change the car while the engine is still running, n times before the 2nd Java car arrives. The language is Clojure.
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.
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.
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.
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.
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.
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.
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.
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.
In my experience those more subtle questions are much harder to raise once a prototype is working - "why does the team's experience matter? look how great it works! If you don't block it we could get this to production in a week by just polishing the prototype!"
We write a design doc. Then make small incremental changes in a PR to rollout the functionality. Our git histories look clean and orderly. Like a steady march of progress.
Who imagines this? Professors who teach software engineering classes?
This reminds me of people who think that you write prose (essays, stories, novels, etc) by writing an outline and then "filling it out" with prose, as if in the process you will never discover anything that requires you to rewrite or restructure the document. Nobody writes that way. First drafts are always terrible and basically all good writing has been heavily revised.
Writing code is much more like writing than it is like building a house or a bridge.
I use GitHub issues for this myself but that's functionally equivalent to using a PR - a PR is effectively a GitHub issue with an attached branch of code.
I wrote more about my process here: https://simonwillison.net/2022/Jan/12/how-i-build-a-feature/...
THAT should live in the same repository as the code itself, and updates to it should be enforced as part of code review.
Design documentation that describes the process that got to that point should live separately from the repo in something like GitHub Issues, because it's not guaranteed to be up-to-date but can still be referenced during code archaeology sessions when trying to figure out WHY the software is the way it is.
Commit messages work too, but I prefer to have a short commit that links to an issue thread where I can find out more.
I wrote about this here: https://simonwillison.net/2022/Oct/29/the-perfect-commit/#do...
I think it’s healthy to treat design docs like a historical artifact - true at one point in time. It’s less likely they stay up to date to reflect reality.