[0xEFF]

A short system design doc with a working prototype is vastly superior to a 50 page design doc with no code.

Think of it as the scale model of the house in the original example. It’s a way for sake holder to see and feel what they’re going to get.

[tsimionescu]

Sure, but a few days of intense dedicated discussions /white boarding with a handful of senior engineers can save you from throwing a bunch of different prototypes at a wall to see which one sticks.

[corytheboyd]

Controversial as it may be I completely agree. Maybe I’m just not on the same god tier level as the rest of you but I have done the days/weeks of planning carefully without touching anything close to code “because you’re not supposed to” and there still ends up being things we didn’t think through that become obvious at implementation time. I agree that coding and planning don’t have to be mutually exclusive

[spdionis]

I think spending days on planning is really valuable. Spending weeks is counterproductive in most cases.

[sanderjd]

Figuring out exactly what code to write is not the goal. Figuring out approximately what code not to write is.

[billfruit]

The thing is engineers in other engineering disciplines have documentation that lay down things to the minutest detail. So is it not a good idea for software specifications to do the same, instead of having a brief design document missing huge amounts of design details.

Abridged and abstracted documents add their own confusion.

[sanderjd]

Agreed! And this does not contradict what I said. I think it's easy to swing too far in both directions.