[OliverJones]

If you're seriously interested in this topic, it's worth taking a look at Jen Pahlka's book Recoding America. https://www.worldcat.org/title/Recoding-America-:-why-govern...

Ms. Pahlka crawls through some large-system horror stories, and some success stories. The horror stories share something in common: design documentation that outlives its usefulness, takes on a life of its own, and drives implementation decisions in harmful directions.

Brandow's article (the subject of this thread) emphasizes the usefulness of documentation. And it's certain that long-lived software systems (like his php example) need excellent documentation. That documentation is targeted at people like many of us. It answers questions like, "how do I use that blankety-blank IMAP module?".

But long-lived documentation is often misunderstood and misused. For an overstated example, some "non-technical" administrator might read the php docs and somehow infer that "systems developed in php MUST use the IMAP module, or it won't pass acceptance testing." Then, the developers -- employees of some contract development team -- will comply. They'll have to figure out some way to incorporate email store-and-forward systems into the product, even if it makes no sense to do that.

There's a danger inherent in extensive documentation: it WILL be misunderstood in the future, and those misunderstandings may turn out to be costly. More systematic documentation -- for example boilerplate "scope" sections at the beginning of docs -- are not a great way to mitigate that danger.

Seriously, go read Pahlka's book.