4 ms·

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

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.

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.