Agreed. FWIW we technical writers (TWs) are well aware that we'd have more business-world respect if we could show more causation between our work and desired business outcomes. Turns out it's a tough nut to crack, judging by all the TWs I've seen work on this problem over the years without figuring out broadly scalable and repeatable systems. So we're stuck in this suboptimal zone where biz leaders know they can't get rid of us completely because Bad Things Clearly Happen More when you stop having someone dedicated to docs, but we often can't show compelling value beyond that.

There was a fascinating report last year suggesting that above-quality docs correlate with increased eng productivity across the board. My intuition says it's true but IMO we need to do more work proving that this connection is legit... the methodology and report writing itself is too complex: https://cloud.google.com/blog/products/devops-sre/deep-dive-...

Docs metrics are worth so much. There's a tendency to overindex on support case deflection, which is often measuring a negative (how many support cases did we NOT get because self-service was so good). And if your docs are great, support is going to have fewer easy questions ("where do I find X? How do I get started with Y?") but more questions that require escalation earlier in their lifecycle ("I followed the great instructions but my obscure infrastructure gave me an inscrutable error message that applies only to me and no other customer").

I've often found that unsolicited customer sentiment is a hit, especially for customers won over from a competitor who either call the docs and self-service options a reason for switching or winning, or immediately call them out positively after switching.

In a holistic sense docs are also supportive for tech and retail support. They act as a reference, a knowledge base, and a place to point users.

Mind elaborating more?

A statistical analysis is the definitive answer to the skeptic's question "Prove that docs deserve more respect." And to be able to answer that question you have to observe what happens to business outcomes with and without docs then perform a statistical test to see what the difference is, judged against its cost. It's thankless work, I imagine.

Lobbying like you've done with this essay is a probably a better investment of your time. Now you simply have to make sure the right people read it and decide to do it :)

I mean, in principle I don't disagree. A quantitative kpi that shows before and after is usually measured differently for each product you're building docs for.

For example, if you have a developer tool, the number of devs you can successfully onboard after you have solid documentation up and running is an effective strategy for getting unimaginative middle managers to understand the value.

Generally the people I work with have already come to the right conclusion because they have tried everything else and not gained the traction they believe their product deserves.

Experimental docs withdrawal? That sounds a bit too extreme and harmful for any business. Unless you had a different technique in mind.

If their utility is in question, then the company does not consider withdrawing them extreme! If it turns out to be harmful, QED! When you perform a statistical test, you only have to expose as many users to it for as long as needed to achieve statistical significance. Not all users will be affected; you need to be able to make a comparison.

The foregoing assumes the alternatives are having docs or not. If the alternatives are something else, such as having different kinds of documentation, then the test treatments will be chosen accordingly.

Would you do the same with, say, the UI? Or an API?

Again, you have to define the alternatives. APIs have launch success criteria too. One way to assess zero-to-one initiatives, if that is what you are asking about, is to start measuring before the project is complete. For a UI, that could be as soon as it is usable but before all the features are implemented. Then you will be able to able to estimate the value of the remaining features.

You might like to read https://hubbardresearch.com/publications/how-to-measure-anyt...

The need for some things to require statistical evidence and for others to be accepted wisdom, devoid of evidence or maybe a hand wave at most, is a form of politics itself. It is why we have agile, open plan offices and shite docs!

One way to frame the business value of docs is equating it to design. Design is understood to be important, but not strictly tied to hard metrics. And the overall benefit is to improve the user experience. You can then measure more qualitatively.

You're not wrong, but FFS it gets old having to constantly justify your existence in a corporate structure unless you're in Sales. People don't get into technical writing to have to detour into instrumentation, stats modeling, etc. They want to do the work, not a bunch of work to justify doing the work that everybody (except executives) understand needs to be done.

Just once I'd like to see the burden put on decision makers to understand the needs of the business they run instead of having to make pretty decks they can pick over once a quarter when trying to figure out what line items to justify cutting to get a better bonus.

You can't do all this alone; you need allies. So use your communication skills to persuade a suitable sponsor with the power to assign the necessary resources. Google and DX regularly release reports about these things; e.g., https://getdx.com/blog/documentation-culture-engineering/

You could use them to raise awareness in your organization.