3 ms·

Very detailed design documents can also be lovely. I've personally worked at a few organizations where expected behavior was ironed out before we started buildi

by mighmi 3y ago

Very detailed design documents can also be lovely. I've personally worked at a few organizations where expected behavior was ironed out before we started building it. (Banking, Engineering etc. will be used to decision flows, so this can be common.) The Million Man Month covers the effectiveness of good schematics. However the technical people needed to work them out with stakeholders can be expensive to have fight with stakeholders for ages, so it tends to be rare. And of course many domains are unknown, so you just keep reiterating until something sticks. Modern agile sucks, but if you read the old discussions on c2.com of how agile appeared e.g. https://wiki.c2.com/?AgileProcesses https://wiki.c2.com/?AgileProcesses there really is a lot of value to find, learn and apply. Of course, the ninjas, blackbelts and cargoculters kill that.

amelius 3y ago
I wouldn't be surprised if the majority of HN readers doesn't even know what a good requirements document looks like.
- mikewarot 3y ago
  This is going to seem weird: An MS-DOS based program in GWbasic, or Turbo Pascal from the 1980s, or a Visual Basic 6 prototype that someone wrote in the 1990s and still gets the job done, or an excel sheet/google doc that someone does to do the calculations "by hand", are all excellent requirements documents. They do the work, are executable (so you can test against their behavior), and already account for all the normal error handling, etc. The people who wrote them saved you a few trips over the waterfall, and perhaps a decade of grief and work. Your closest bet today is to fire up Lazarus anywhere, or VB.NET on a windows box and quickly build the prototype. Once everyone agrees on its behavior, then you're back to the races again. Get buy in on a single quick and dirty prototype, then scale up from there.
  - pif 3y ago
    > ... are all excellent requirements documents. No, they are not! They can be a wonderful resource for the validation tests, but a developer needs a model to start. The documentation of existing tools may be a nice requirement document, provided it is exhaustive enough. By the way, every time I was requested to implement something "exactly like this gizmo here", I proposed to just keep using that gizmo there, and then the discussion became interesting: "No! We want the same, but...." As soon as the "but" was pronounced, the person in front of me realised the gravity of the situation: they didn't know what they wanted, and by handing me an ancient (despised) tool they were just planning for me to fail and for them to throw me under the bus.
erik_seaberg 3y ago
I’ve seen design docs that are vague, and design docs that are so detailed and specific that they can’t be kept up to date. I don’t know that anyone has found a happy medium.

by mighmi 3y ago

amelius 3y ago

I wouldn't be surprised if the majority of HN readers doesn't even know what a good requirements document looks like.

mikewarot 3y ago
This is going to seem weird: An MS-DOS based program in GWbasic, or Turbo Pascal from the 1980s, or a Visual Basic 6 prototype that someone wrote in the 1990s and still gets the job done, or an excel sheet/google doc that someone does to do the calculations "by hand", are all excellent requirements documents. They do the work, are executable (so you can test against their behavior), and already account for all the normal error handling, etc. The people who wrote them saved you a few trips over the waterfall, and perhaps a decade of grief and work. Your closest bet today is to fire up Lazarus anywhere, or VB.NET on a windows box and quickly build the prototype. Once everyone agrees on its behavior, then you're back to the races again. Get buy in on a single quick and dirty prototype, then scale up from there.
- pif 3y ago
  > ... are all excellent requirements documents. No, they are not! They can be a wonderful resource for the validation tests, but a developer needs a model to start. The documentation of existing tools may be a nice requirement document, provided it is exhaustive enough. By the way, every time I was requested to implement something "exactly like this gizmo here", I proposed to just keep using that gizmo there, and then the discussion became interesting: "No! We want the same, but...." As soon as the "but" was pronounced, the person in front of me realised the gravity of the situation: they didn't know what they wanted, and by handing me an ancient (despised) tool they were just planning for me to fail and for them to throw me under the bus.

erik_seaberg 3y ago

I’ve seen design docs that are vague, and design docs that are so detailed and specific that they can’t be kept up to date. I don’t know that anyone has found a happy medium.