A free GUI tool.

Scenario-based writing is a strategy that utilizes real-life situations and narratives to engage people. By adding real-life scenarios to documentation libraries, teams can create more engaging, relatable, and compelling content for users. This approach to writing helps people find answers to their questions that arise during real-world situations.

Photo by Daniel Thomas on Unsplash

How Scenario-Based Writing Helps Improve AI Results

Incorporating scenario-based content into a product's technical documentation portal can significantly enhance the effectiveness of generative AI tools in addressing "why" and "what" type questions.

Scenario-based writing enhances the self-service content experiences increasingly provided by technical documentation teams. Infusing real-life scenarios into documentation libraries makes the self-service experience more engaging, relatable, and compelling.

Scenario-based content provides context for users to understand a product's practical applications. Incorporating this content into a documentation library enables generative AI to generate more relevant and insightful responses. By understanding the context in which a product is used, the AI can better address questions about its purpose and functionality.

Why How-To Content Is Not Enough

Large language models (LLMs) like OpenAI's GPT-4o generate human-like responses. Their effectiveness relies on the quality and comprehensiveness of their training data.

Traditional technical documentation—such as step-by-step procedures, reference data, tutorials, onboarding instructions, and quick-start guides—lacks the contextual depth needed to deliver the types of complex "what if” and “why” or "why not" answers users seek. This gap can cause LLMs to produce incomplete or speculative responses, a problem known as hallucination.

The Role of Scenario-Based Content

Scenario-based documentation fills this gap with rich, contextual narratives beyond procedural instructions. It explains the reasoning behind features, design choices, and operational constraints.

Incorporating scenario-based documentation allows LLMs to access a broader, more nuanced dataset, enabling more accurate and relevant answers that address specific user needs and challenges that standard how-to guides usually do not cover.

Incorporating this scenario-based product content into a unified product documentation library helps LLMs better understand the reasons behind user inquiries. For example, when a user asks "why not" use a particular feature, the AI can use scenario-based examples to explain potential limitations or suggest alternative solutions that fit user needs.

MS Office files, XML, markdown, plain text, and more.

When I talk to writers about this, I state the case strongly: every topic should be able to fit anywhere. That always provokes some pushback, which is good. Of course it’s not really so, in practice. There are many combinations of topics that are just never going to happen. However, on a large scale, with hundreds or thousands of topics, there are many, many plausible combinations, some of them completely unexpected.

In fact, there are so many plausible combinations, you might as well not worry about the impossible ones. You might as well just go ahead and write each topic as if you had no idea what parent topic it was going to be pulled into.

That’s what we mean by “unleashing” your content with DITA. It’s the combinations of topics that bring the value, not the individual topics themselves. If you draft each individual topic so that it’s eligible for the largest possible number of combinations, you’ve multiplied the usefulness to the user (yes, and the ROI, and the technical efficiency) of the information in that topic. For any given topic, it’s true, there may be only three or four conceivable combinations in which it could make sense. For some, there might be hundreds. You’re not going to know unless you write for reuse in every case.

Once we’ve put this into action, we can go back to the managers and gurus and say, now you’ve really got ROI; now you’ve really got efficiency. Because we’ve given you something that is worth investing in, something that’s worth producing efficiently. Something that can delight readers with its usefulness and its elegance. This isn’t just content, this is writing.

In any information set, every component should be able to roll up into what is ultimately a single top-level summary. We know most readers don’t come in through the front door, but in principle you can provide the reader with an entry point that fully sums up what’s in the information set. From there they can drill down into more and more detailed levels. (Readers can be very easily trained to do this, because they have learned from their previous reading to scan for summary-like information and use that to judge whether it’s worth reading on for more detail.)

If each level is itself a rolled-up collection of subordinate units, and so on in turn down the ranks, what you are offering is a set of pages in which each page is itself a table of contents. The content is the navigation and the navigation is the content.

Picture this single page sitting at the apex of a pyramid. It contains (describes) everything that is included in that pyramid. Not that many people are ever going to actually read that page, but we need it to be there, because it defines the pyramid.

The bigger the pyramid, the higher level the information in its top node is going to be. So, for a very large information set, that single page is going to be very general. Each of its immediate child pages will be a level more detailed, and each successive level is going to be more detailed, until you get to the bottom “leaf” level where a topic describes only itself.

 

The most disorienting thing about learning structured writing is modularity. There are a lot of things we’ve learned about writing that we have to unlearn; this is the most fundamental of them. This is way bigger than deciding it’s OK to dangle a preposition.

Modularity means, in practice, conveying meaning in free-standing chunks instead of in a unified stream. Why is it so great to be free-standing? What does that get me, from a purely authoring perspective? (Remember, we’re still excluding managerial and technical perspectives from this conversation. You folks can come on back later.)

In mature DITA writing, many topics are built up automatically from component topics. Done well, these composite topics look like you lovingly handcrafted them with sections, section titles, section detail, overview material, and so on. In fact, you threw them together on the fly from component topics that you happened to have lying around.

How good your built-up topics are depends on how good those component topics are. How good the components are is largely a function of how well each one delivers meaning on its own, without having to wait for any other component to its job.

A composite topic that looks and reads like a composite topic is a failed composite topic. It needs to look and read like it was specifically conceived for this particular user at this particular moment. We want its component topics to match, in tone and style and scope, so well that they look like they were all written at once for this specific collection.

You’re working on a building, from the roof down and from the foundation up at the same time. You know what you need your built-up composite topic to do, which influences how to you’ll define and select or draft its component topics. At the same time, as your component topics come into being, they’ll influence the scope, scale and ultimately the effectiveness of the composite topic you’re building from them. In my experience, it’s when this process gets rolling that you really start to feel like you’re doing interesting, useful writing. This is where the fun starts.

I’m reprising something I put up on this site about five years ago (lightly edited), because it still comes up in conversation occasionally and it’s fun stuff to talk about. Goes a little bit like this:

Writing has a tense, complicated relationship with speech. Good writing gives the illusion of resembling speech, or being derived from speech. But writing that is transcribed from speech is generally bad writing. It doesn’t feel like real speech. Some writing that does feel like real speech seems stilted when you read it out loud. The speech that writing evokes is imaginary speech, speech that takes place in your mind’s ear.

Often someone says something in a meeting that captures a thought perfectly. It may even seem elegant, like something that everyone knows but that hasn’t been expressed so well until now. Someone will say, “Get that down.” Later, at editing time, it turns out to make no sense at all. The context has changed, of course: what’s said in a meeting grows out of the experiences of everyone there, complete with unspoken assumptions, agreements and compromises. Text has little or no context. It appears out of nowhere, bearing all of its antecedents within itself. It has no hope of matching the immediacy of a spoken conversation. But we can rely on it to a degree that we can’t rely on our memory of speech.

Let’s leave aside, for now, the whole technical thing. Let’s separate creating content from building deliverables, at least abstractly. Let’s just talk about how we can use DITA to create beautiful, thrilling texts.

The first thing to acknowledge is that DITA is not just an XML-based way of producing the same kinds of products we used to push out with Framemaker. (That would be DocBook.) DITA is so much more than that. It’s a new way of writing. It invites us to look at our writing in a completely different way.

When people talk about DITA they almost always talk from one of two overlapping perspectives: the technical guru or the publication manager. Writers have reason to care about some of the same things those two care about, but neither focuses on what really matters to tech writers.

• To the technician, DITA is mainly about all the awesomely efficient processing and automation you can do. To a writer, efficiency is great as a means to get good writing in front of readers. It’s not an end in itself.

• What sells DITA to a manager is the cost savings from reuse and processing efficiency. Writers care about saving money too — to hire more writers with, of course — but investment only matters to us if it’s in pursuit of better content.

I suspect that’s why there are a lot of DITA-based help sites out there that aren’t really much better than the old paper or PDF or Winhelp or Dreamweaver products that they replaced. Gurus and managers have reconfigured their thinking, but writers haven’t. We’re still trying to write the kind of stuff we grew up writing, and trying to jam it into a new kind of container. But this new container demands a new kind of content.

There has been a steady stream of upbeat, expansive reports on the future of mobile marketing and advertising (most of which—if you track these sorts of predictions—tend to wildly overshoot their mark), coupled with prognostications that the internet as we... Astoria

There appears to be a growing trend among content publishers of using targeting technologies to focus and solidify their relationships with their customers, rather than passing customer data to their ad network ecosystem. Although the benefits of this type of ... Astoria

Mobility trends are clear and undeniable, it is not just that the global market for mobile devices is now measured in the multiple billions, but also that the next generation of mobile devices has gained traction at a remarkable rate.... Astoria