Item — HN Reader

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" ;)

5 comments

> 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.

This is more closer to throwaway code than design docs.

Why not both? And it can be done productively: start coding (prototyping) if planning is difficult and vice versa.

That rests on the assumption that you'll notice that planning is "difficult". Whereas what I've usually found is that people build elaborate plans and feel like they've made progress doing so, only to discover when they come to implement them that there was a false assumption in step 1 that renders everything else pointless (or, worse, the plan should really be fundamentally reconsidered in the light of this info, but you've spent all this time on it, and it's not outright impossible to keep following it, so...).

An extension of this is what I call problem solving by differentiation. People who don't understand the problem space defer the part they don't understand by creating premature abstraction upon premature abstraction. In their head they seem to be slicing up the problem until there is none left, but in practice this continues until they finally understand the core domain problem or someone who does gets assigned. But those layers of abstraction don't die...

I thought this is a solved problem. Steps:

1. Have some long term goals.

2. Design a small iterative improvement or a minimum viable product that should bring you closer to your goals.

3. Build just that.

4. Reevaluate.

I.e. I thought the idea is to embrace changing the approach or even pivoting when necessary.

It is. But for some reason a lot of people prefer to spend time planning and even moralising about how virtuous they're being by doing so. Frankly I'm convinced it's more of a cultural, Protestant-work-ethic type issue - you can't reason people out of planning because they never reasoned themselves into it in the first place.

Came here to say this.

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

I enjoyed the writeup and think it's a nice idea depending on the situation, but with serious limitations (for context, I also do prototype first, but still right a design doc at some point)

The main issue to me is exactly that we do throw away the prototype implementation.

Writing rich documentation for throwaway code is tedious, and at the early stages I see a split between the people that mostly read the doc and only glance over the code, those who almost ignore the docs and focus on the code, and some rare people actually looking at both and getting confused at the discrepancies ("you say you in your doc you store values in the remote database, but this code only writes to the local one, which one will stay ?")

Perhaps I'm just not good at docs, but doing code heavy prototypes with only very light and high level doc was way more efficient.

Then when we settle on one direction, I can freeze the main points in a separate documentation and rewrite the prototype in a more serious version.

Having a separate design docs also helps when the system components are split across many area. Having the doc even when it's a compact proposition standardizes the process and you never have to ask upfront if it will be needed or not.

I have to say that I completely disagree with you on this, but I also understand that I am a lot more comfortable writing prose than the average programmer.

A draft PR with rich documentation doesn't often communicate the "whys" and the "why nots" nearly as well as a well-written design document, or the high-level goals of a piece of code. It also is much harder to share with the product and business sides of a company which may be less comfortable with the idea of reading code.

A great design doc can reduce non-obvious problems to trivial and is usually written alongside a prototype (if the thing is simple enough).

I will give you that if you are instead competing with a poorly-written design document, a very well-documented PR may be a good alternative.

Right on the money:

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.

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.

Some software, in absolute, has to be as safe as a quality concrete dam: think 737 MAX.

Other software, perhaps not so life-or-death, …but with which side of that “spectrum” would you like to run your business or project of importance?

The USAF has put these things to paper quite some time ago: reliability, repeatability, reproducible process, and quantification (even if in a statistical interval), etc.

The problem with software is that making one more unit has a marginal cost of zero. And, going from “prototype product” to “production product” is a mere file rename away. So the temptation to see one more bug as a fact of life is always there - and that makes the thin line between Engineering and a DIY hobby being usually far too thin.

> Don't forget: "weeks of coding can save hours of planning" ;)

Also, "weeks of planning can save hours of coding" :)