Focus on decisions, not tasks

Thanks for sharing. A couple of thoughts.

It seems like it's a lot harder to measure whether your docs are helping people make good decisions than it is to measure whether they are helping people successfully accomplish a task. I think we optimize for task-based/procedural docs because the business needs us to prove our value, and there is a need for this type of documentation, and there are lots of ways to measure and report on it over short timelines. But answering the question of, "Did this docset help someone build the right thing in the right way", I mean...organizations struggle to answer this question about their own products, abstracting that to try and measure the effectiveness of your docs seems super fuzzy.

Which is not to say you can't write docs that do this, just that it seems very hard to use numbers to prove that you have done so. I definitely think I could rank how well different docsets support users who need to make decisions, and I could offer up explanations to support my reasoning, but I don't know how to quantify that for the business.

I wonder how the structure of a docset that is designed to support decisions differs from that of a docset that supports tasks. I expect you'll have the same main categories (conceptual, reference, guides) but maybe a lot more conceptual docs, and more space dedicated to contextualizing the concepts. I would expect to see topics become more interdependent, more cross-references, etc.

Interesting that your first thought here is not, oh, how can I use this to improve the docs I am writing, but it is, how can I prove that this improves the docs I am writing. You seem to live in a though environment.

You're getting a taste of the world that a lot of professional technical writers live in. Everyone seems to intuitively understand that you need docs, and that if you don't invest in docs it probably will be bad for the business, yet at the same time it's hard to concretely show business value. So technical writers are incessantly asked to prove their value, even though the managers subconsciously know that they're important for some reason. Over the years I have come to believe that docs are important simply because it's a primary mechanism for sharing knowledge across the company and to customers. Michelle Irvine has been doing great work quantifying this: https://cloud.google.com/blog/products/devops-sre/deep-dive-...

In my own personal projects, where I'm free to do whatever I think is best for my users, I will probably adopt "support decisions" as the foundation of my docs strategy.

In the spirit of working with integrity, if I feel that "support decisions" is the best approach for my own projects, then I probably have a duty to bring this strategy into the docs I do for work.

Luckily I don't have short-sighted managers breathing down my neck, but if I had to convince people at work I would go about it like this:

* Explain the logic of the strategy. Supporting decisions just seems to make sense and ring true . The tasks will still get documented, but tasks are just a subset of decision support.

* And then I would provide a long list of examples from support tickets, chat room discussions, etc. where lack of decision support seemed to be the problem. For intellectual honesty I would show the complete list of docs-related support tickets (for example) and then the subset that were related to supporting decisions. If it's a non-trivial percent (maybe 25%) then we should really look into "decision support" more.

* Last, I might provide examples that the stakeholders themselves have faced in their own work. "Remember how difficult it was to decide what CMS to switch to??"

You're not wrong. Business is a tough environment.

At a gut level the post seems sensible to me, and it does generate a lot of ideas about how I can make my own docs better. That's not enough, though, if I want the folks who think about docs at my org to change their approach.

As the OP states in several other comments, most writers and organizations learn to prioritize task-based documentation. If we want to adopt a better way of doing things, we need to be able to communicate why it's better. It's no different in other disciplines.

Thanks for sharing this post from Michelle, just shared it with some leaders at my company!

Exactly. Or you become an island doing the good but sometimes barely scratching the surface of what could be possible (to the detriment of your users).

Another aspect of this is that it may take you more time to complete your assignments and you get labeled as slow.