News for hackers. Stuff that matters.
Re:What Makes Developers Productive? by mighmi on Sunday July 16, 2023 @12:36PM (#36748849)
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 there really is a lot of value to find, learn and apply. Of course, the ninjas, blackbelts and cargoculters kill that.

Re:What Makes Developers Productive? by amelius on Sunday July 16, 2023 @05:25PM (#36751546)
I wouldn't be surprised if the majority of HN readers doesn't even know what a good requirements document looks like.
Re:What Makes Developers Productive? by mikewarot on Monday July 17, 2023 @12:01AM (#36753916)
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.

Re:What Makes Developers Productive? by pif on Monday July 17, 2023 @03:40AM (#36755233)
> ... 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.

Re:What Makes Developers Productive? by erik_seaberg on Monday July 17, 2023 @12:22AM (#36754075)
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.