> Management hated that

There's a subtle but important thing to note here. My bet is management didn't hate that you did a POC. They hated that you DIDN'T also do a writeup.

It's not about this vs that. Meet the minimum requirements before you go doing extra.

It’s all about communication. I think of a POC as way to communicate what it is that needs to be created. I think a document is another way of communicating what needs to be done. Mandating one or the other seems like a fools errand to me since each one has strengths and weaknesses.

Frankly having been that manager, the demo shows what you’ve done. It didn’t lay out how to get the whole project there.

The documents are hard specifically because not you have to consider alternatives, or the feasibility of executing. What security concerns did I cover? How much time do I need to spend convincing team y to add this feature?

The demo is always the easy 50%, and never the hard parts that cause you to spend two years building alignment and executing.

As always, nothing in the world can take the place of prudential judgement. When proposals should be written up to avoid senseless action and short-term thinking, and when they should be avoided because they would constitute bikeshedding or overthinking or whatever, is a matter of prudence and competence gained through experience. There is no algorithm that will allow you to mindlessly come to the correct decision.

A demo is no substitute for a written proposal and vice versa. The first is empirical, the latter is analytical and deliberative. Each has its proper place. Really, the demo is a way to corroborate the proposal, so it's a question of how rigorous the proposal needs to be. Some minor tweak might only require a quick discussion while a deep change will require deeper consideration.