First published on TECHNET on Mar 16, 2009
In my last post,
Creating Project Guidance
, I talked about how we produce scenario-based documentation and mentioned something called narrative documentation. This post gives some more detail about what that is.
For the Service Manager documentation, we are weaving a realistic (though fictional) scenario throughout the documents to help you understand context of a particular procedure. If you've looked at our Beta 1 documents, you may have noticed that we have named people (for example, Garret and Phil) that we talk about as we introduce procedures or product configurations. We also talk about a specific company that they work for (Woodgrove). Our hope is that as you're first learning the product, you'll recognize some of these people's roles from your organization and be able to quickly map the procedures we have in the guides to people and procedures in your organization. As we talk about
why
people are doing things, we want to make it easier to learn and remember how specific procedures fit into the big picture.
In addition, one of the early discussions the documentation team had was about the desire to include concrete examples for each how-to. We think learning information (such as learning a procedure) is easier when you're doing something specific instead of something abstract -- so you're not just reading about "creating an incident", you're "creating an incident for a broken printer". The tension here is that we can't write something so specific that it's unclear how to create a different sort of incident, or that requires knowledge of our overall narrative. (I don't want to be required to know Garret and Phil when I'm looking up a procedure for reference, and I suspect you wouldn't either.) We solve this by including copious "for example, type..." sentences in our how-tos. Because these examples relate to the Woodgrove bank scenario, you can follow the storyline from the introductory text down into the procedures. If you don't know or care about Woodgrove, they're easily skipped.
Early feedback on this approach has been positive, but we welcome additional feedback about our implementation. If you have a comment about the documentation or want to contact the doc team, feel free to drop us a line at smbdocs (at microsoft.com).
