August 2012

Developing Scenario-based Content

CIDMIconNewsletterMargaret Parsons & Julie MacAller, Microsoft Corporation

Scenarios, scenarios, scenarios. Seems like everyone is talking about them these days. And why not? Seems to make perfect sense to build your product around your customer’s goals, behaviors, and use cases. This article represents our thoughts on scenario-based content and what we’ve learned from transitioning to this kind of content, both from the perspective of a writer and a manager. Between us, we have over 20 years of experience with creating technical documentation at Microsoft. Our teams focus on developer documentation. The job of explaining each piece of the platform, what it does, and how to write code that makes it do something, falls to us. As our product teams have moved to scenario-focused engineering, we’ve been figuring out how to apply the same principles to our documentation.

How do we think about scenarios for content and how do we move from a world where technical help explains what a product does to a world where it explains why you should care? As we began tackling this issue, it became obvious that the content we’d produced had been meeting the customer’s needs only somewhat. Yes, they needed to know what features are in the product, and yes, they needed to know how to use each feature. But more than that they needed to know why each feature is included, when to choose one feature over another, and how to put all that together in the application they are building.

Typically, we’ve broken writing assignments down by feature area. Each writer is mapped to a product group that produces that feature. So historically our process for developing content has been fairly straightforward—each writer works with their product team to figure out what new features are under development and approximately how much content is needed to explain the new feature. When you start thinking about scenarios though, it no longer makes sense to plan and develop our content that way since a particular feature might be useful in more than one scenario.

One of our first steps was to help writers and managers understand what we mean by the term “scenario.” We had some smaller efforts to create scenario-based content in the past, but not everyone understands the term in the same way. We’ve used team meetings and broad communications to help with that understanding. Even our tracking system has helped indirectly, since we created work items to track content stories and content tasks and provided definitions of the difference between the two and how they related to product team scenarios. And it’s important to recognize that our product teams, being new to scenario planning, often write scenarios that are either too vague, too specific, or not conducive to anything in particular (think “Joe Developer loves Product X!”), which leaves us to lead the charge.

And that immediately leads to the question, “What makes a good scenario for content development?” I’ve been asked this question by many people, and my answer isn’t anything prescriptive. You really have to start trying to build scenarios to begin to understand them. A good scenario represents something meaningful that your customer wants to achieve. It captures who your customer is, why the scenario is important to them, how they come to the scenario, and what success looks like when they are finished. Also, especially for technical content, it is important to consider what they will want to do next.

Scenario-focused engineering ideally involves four steps. Observe customers, define scenarios, consider multiple options, and prototype and build. What does this look like when content is your product?

Observing customers involves gathering as much information from whatever sources you have about who your customers are and how they behave, not only with the product, but also with your content. For example, you might have customers who are very technically advanced, mostly like to play around with stuff, and don’t like to read help documentation unless they absolutely have to. In this case, you would not want to plan to write a bunch of beginner, entry-level content. Instead, you’d want to try to figure out when the customer would “absolutely have to” turn to the documentation and those would be your scenarios. Also, if you have information about how customers use your content (and if it is on a website, you probably do), it is helpful to know how they find content on your site, what kind of content is popular, and so on.

When defining your scenarios, make sure they are clear to both the people you’ll be vetting them with—product team, management, potential customers—and the people eventually writing the content. The writers need to understand who they are writing for, what those people already know, how they like to learn, and where they go to find information.

Considering multiple options is fairly obvious for a product and a bit less so for content, but there are a lot of options when writing content, especially online content, to consider. You can play with content type—should it be written text, video, code, art, and so on; style—professional, casual, chatty, minimalistic, funny, and so on; and channel—where you publish your content is extremely important if you want that content to be successful. Is your target customer someone who will come to your website and look for help or are they likely to ask for help on a community forum? Are they willing to take the time to read through 25 pages of documentation or will they just want to download a code sample?

Next, I encourage each writer toward scenario-focused documentation as individuals. Doing so was helpful. Now instead of just defining what the feature is and showing a bit of code, writers are actually showing a small use case for that feature and choosing (sometimes with guidance from their managers) the most important, interesting, and relevant use case. When we produced this content for our last product release, the results were overwhelmingly positive. Customers said things like “this is the best beta content I’ve ever seen.”

However, application development, like many things, is not a set of small use cases all run together. Instead, each feature of the platform generally relies on other features and must be combined to help customers understand what the features can do together, which is where the real power lies. This makes it hard to break out individual use cases in a meaningful way.

So, where does that knowledge leave us? In our case, we are trying to move to what we call “end-to-end” scenarios. Instead of starting at the bottom and trying to build a documentation set up out of all the most granular pieces, we want to start at the top. We take the large customer scenarios that the product team started with and break those down into “stories” that we can explain to the customer. These stories, then, help us meet our goal of creating content that is more relevant and more useful.

To really push the team forward and get writers to start working together and building end-to-end scenarios, it’s important to make sure the managers are fully committed to scenario-based content and understand it well themselves. That is the only way they can coach their teams effectively. One of the best methods I’ve seen a manager use with his team was the simplest: patience. He worked one on one with the members of his team to help them not only understand but apply scenarios-based thinking to their content areas. He answered their questions and allowed them to take as much time as needed to fully understand. What he understood about the new direction and what he passed onto his team members was that, in a sense, you will never truly understand scenario-based content until you do it yourself. Until then, you can imitate it but it needs to become a new way of thinking for you. Now we are working to spread that way of thinking throughout the organization.

It can also be helpful to “seed” teams who are new to scenario-based content with members or managers who are familiar with it and have done it themselves. We have had some opportunities to work cross-group with another team whose approach has always been scenario-based. They usually write content against the currently shipping product, while we usually write against the newest, not-yet-shipping product. But creating a team composed of members from both groups means that those who are comfortable with scenario-based content can share their expertise with those who are not, and those who know the challenges of working with pre-release software can share their hard-won experience with those who are not. I am looking for opportunities to increase these cross-group experiences. Those who have been involved in the few we have had to date have been very positive about the experience.

Our first pilot for this new approach involved bringing together writers and editors from our team and a developer and tester from our partner team to create a new team that would build end-to-end scenario content for our new Windows Phone developer platform. The new team got together and brainstormed the components that make up typical mobile applications. Then we set out to build a prototypical mobile application—something very simple, but containing the key elements that most developers would need to use in any application. We considered all aspects of the development process, including design and publishing, which aren’t usually part of our documentation for developers.

For the writers, the process of building a complete application instead of just bits of code was a new and exciting experience. The help from our team’s experienced developer and tester ensured that the writers learned new skills and considered aspects of the development process that they wouldn’t normally encounter. Writing the content was extremely challenging for the team, and we kept slipping back into our old style of feature-based documentation. We went through many group editing sessions, restructuring the content, and rewriting before we were finally happy with the outcome. The content has done extremely well on our site, and anecdotal customer feedback tells us it is some of the most popular phone content we’ve produced.

We’ve had several teams get together to reproduce this effort in the past year, sometimes forming working teams with our partner teams and sometimes just creating small teams on our own. However, we are still far from our goal of producing all our content from this end-to-end scenario model. We’ll get there; we are committed to it.

As a manager, I prefer to give teams time to grow into new strategies, rather than to make sweeping changes. It’s easier on the teams and helps those who are less comfortable with change acclimate themselves to new directions. But it requires patience, since it takes longer to show concrete results in the published content. In this current release, I have continually asked managers to ask writers to consider the story or the scenario in planning and authoring content. This encouragement has helped a bit. But the end-to-end scenarios remain elusive. In the next release, we will focus more on those end-to-end scenarios, and I will push writers and managers harder to adopt a scenario focus.

Moving a team to scenario-focused content development can be a big change for a team. First and foremost, the leadership must commit to the change. Once the commitment is there, like learning any new skill, it requires patience and practice to excel. By giving your team opportunities and support to create this kind of content, you will be able to create content that is more meaningful to your customers and achieves better results for your product. CIDMIconNewsletter

Margaret Parsons

Microsoft Corporation

Margaret Parsons manages the effort to use business intelligence to drive content strategy for the Microsoft developer tools documentation teams. She has worked on scenario-based developer documentation and is passionate about helping technical documentation teams understand more about their customers in order to produce better results.


Julie MacAller

Microsoft Corporation

Julie MacAller manages the documentation teams for Microsoft developer tools products, including Visual Studio, ALM, and the .NET Framework. She knows the scenario-based approach works and has positive customer feedback to prove it, as a result of leading the ALM documentation team to adopt scenario-based content for the Visual Studio 2010 release.