Good Docs Describe, Bad Docs Prescribe (opens in new tab)

This is absolutely wrong. Documentation should describe the intent of the development organization, not its current state. Sure... if you're building a web site, the decision to change the background color to light yellow instead of white probably doesn't need a design review. But if you're building a banking back-end, you probably want to list out a few requirements that aren't going to change (like "overdrafts should be impossible", "you should support multiple, simultaneous transactions", etc.) And when you find that your requirements are difficult to ALL implement, that's a finding. It means there's more to the problem domain than you anticipated and you may need to go back and think about it again.

Documentation is not hassle foisted upon coders by idiot architects. It is (when done well) the artifact resulting from the design process. I sounds like the OP has a history of working for dysfunctional software development organizations.

I think this article misses the mark (sorry op). The author is misinterpreting what the purpose of those documents are. Those are planning documents intended to generate team alignment and shared context. You should co-author them with the important stakeholders and it's a form of thinking through the solution as a group. Of course they describe future state—and that's a good thing.

It sounds like the problem is that nobody in the org ever writes down what the system does in the real implementation, and so the RFC becomes the default? That does sound frustrating, but it's also not the problem/solution pairing that the article tries to tackle. Also—that is explicitly what generated docs solve.

Documents should be unix-y (do one thing well), is maybe how I would rephrase this. If they're overloaded, that is genuinely a bad thing, but RFCs do have a time and place!

Dollars to donuts, you cannot have a high velocity distributed system with dozens of developers without comprehensive docs and long term plans. This article is straight up bad.

There is more than one kind of documentation. Descriptions are great for understanding systems, but runbooks, checklists and such are useful prescriptions.

When you've got a crisis and need to restore the system from backup it's a huge relief to open up a binder and find step-by-step instructions to get it up and running again.

Documentation, not doctors. Got it. That makes so much more sense than what I thought when I first saw the headline.

Generated docs are often crap. I'm not saying therefore don't generate, but I've seen plenty of generated docs that are difficult to read, and difficult to navigate

I find Google's chrome extension docs to be atrocious. Bad formatting making them almost unreadable (FOR ME!) and not enough examples.