The biggest issue that I’ve had with prototyping, is that people consider it “ship” code, and force me to use it as final code.
I find that I’m best served with a hybrid approach, where I spend a lot of time planning and documenting, but basically, for myself, then writing ship-Quality prototype code, so that using it in the end product is OK.
However, if someone tells that design doc writer that this is something like a term paper at school that is being graded, they can actually improve their writing by quite a bit by doing some editing. So the symptom is really the same as prototyping: people write draft-quality design docs and magically hope it to be a good quality piece of writing suitable for a wider audience. What they need is a few rounds of editing, just like when they write prototype code they need a few rounds of refactoring.
You still have to read it back and triple check it, as you would your own work, but you don't need all the time it takes to extensively expand it from draft.
Also, which it is in context it's quite good at documenting what needs to be done to test it.
That's what they said—design prose!
with a weird caveat …
if you don’t have an audience who is willing to read what you’ve edited, editing can be a partially pointless excercise.
last shop i was in i’d edit this stuff to glorious beauty. no-one else would ever read it. i tried presentations instead. didn’t help. i tried live sharing the doc in a meeting, no one cared.
but editing a design doc (or a big PR description or whatever) is always helpful for me as it is a process where i’m editing the problem/solution description without having to move code around.
i’ve done a few good refactors off the back of editing some text/diagrams.
lesson i learned: edit design stuff as if someone else will read it, but do the editing for myself (to learn something or clarify something about the problem/solution).
a) are not good communicators,
b) do not respect you,
c) are afraid to admit they don't understand (even if your doc is clearly shit),
d) do not care very much about the project.