4 ms·

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 desi

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

sevensor 2y ago
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.
- softwaredoug 2y ago
  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
  - makeitdouble 2y ago
    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.
  - pclmulqdq 2y ago
    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.
lmm 2y ago
> 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.
- eek2121 2y ago
  Came here to say this.
- thih9 2y ago
  Why not both? And it can be done productively: start coding (prototyping) if planning is difficult and vice versa.
  - lmm 2y ago
    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...).
    - galangalalgol 2y ago
      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...
DrNosferatu 2y ago
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.
- digging 2y ago
  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.
  - DrNosferatu 2y ago
    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.
- deleted 2y ago
  [deleted]
eadmund 2y ago
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.
shric 2y ago
> Don't forget: "weeks of coding can save hours of planning" ;) Also, "weeks of planning can save hours of coding" :)

sevensor 2y ago

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.

softwaredoug 2y ago
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
- makeitdouble 2y ago
  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.
- pclmulqdq 2y ago
  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.

lmm 2y ago

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

eek2121 2y ago
Came here to say this.
thih9 2y ago
Why not both? And it can be done productively: start coding (prototyping) if planning is difficult and vice versa.
- lmm 2y ago
  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...).
  - galangalalgol 2y ago
    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...

DrNosferatu 2y ago

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.

digging 2y ago
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.
- DrNosferatu 2y ago
  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.
deleted 2y ago
[deleted]

eadmund 2y ago

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.

shric 2y ago

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