Learn to use Visual Studio, Visual Studio Online, Application Insights and Team Foundation Server to decrease rework, increase transparency into your application and increase the rate at which you can ship high quality software throughout the application lifecycle
More videos »
I’m very curious to hear feedback from you on replacing orientation topics with a new thing: scenario topics.
Every node in our table of contents that has children topics is what we call an orientation topic. It generally just contains a list of links to the topics. In some cases it includes some explanatory information about that topic area.
• A plain orientation topic. Working with Work Item Lists in Microsoft Excel
• An orientation topic with some embedded conceptual information. Publishing and Refreshing Work Items..
Unfortunately I don’t think orientation topics are effective at doing their job of orienting you to your location in the content.
Suppose you’ve just done a search and one of these orientation topics comes up in the search.
1. You open it and begin reading the text.
2. To understand what the section of content is about you have to read at least a paragraph.
3. To see if any of the topics in that section apply, you have to scan the topic titles and explanation.
It’s a fair amount of reading to do trying to see if you really are in the right spot.
I’m introducing scenario topics as a better solution. The following picture shows an example.
Powerpoint deck of Scenario cards
Find the complete list of sample scenarios I’ve created so far in the PowerPoint slide deck here. It shows the orientation topics under Managing Work Items in Microsoft Excel and Microsoft Project reworked into a set of scenario topics.
To me, scenarios represent something fundamental. Documentation should map technology (e.g. work item lists) into the problem space the user is working in (e.g. to track project progress). These serve the same purpose as an abstract in a lengthy technical document: Telling the reader succinctly the key points of the content section so they can decide if they need to read any further.
A scenario topic answers two questions:
1. Am I in the right spot? A scenario-based topic should at a glance, or with minimal reading, answer this question.
2. How does this information relate to me? The first bullet list in the scenario answers this question.
Additionally, the scenario-based topic is easy to read and very simple. Each scenario in the sample deck has these key parts:
1. A simple one sentence description about that section of content.
2. A bulleted list of the tasks that you accomplish with that section of content. For example, you use a work item list to track status for a team.
3. Additional bullet lists of information relevant to the technology in that section. For example, how you actually crea te work item lists, dealing with publishing errors, and so on.
4. On the right side is a visual representation of the scenario. This could be an architectural view of the technology, a Venn diagram, a flowchart, or whatever best describes the scenario. The purpose of the graphic is to help someone quickly see the key elements being talked about in that section.
Because this is a slide deck, and not an actual help document, I can’t show everything WYSIWYG. But the bullet lists are all linkable so you could click any bullet item and have it take you to the relevant topic.
I also can’t show the table of contents. You would see the title of the scenario topic. Under that you would see the supporting topics linked to from the bullets. If you look in the notes section of the slides I pasted in the topic titles from the current table of contents and where they would show up.
I’m really looking for feedback on this idea. It is a prototype so I only have a slide deck of what this might look like. I’m curious what you think about it. Is it good? Is it bad? Why?
I’m also especially curious how this would fit into the context of how you find these topics.
1. Is this sort of scenario based topic helpful if it came up in a search?
2. What if it came up from F1?
3. Is there additional context that affects the usefulness of these kinds of topics?
Post opinions here on this blog. Or feel free to send me e-mail at firstname.lastname@example.org. I look forward to hearing your discussion.
I recently attended a course on Minimalism, taught by Joann Hackos. It was a good and right in line with
Take a look at a proposal ( Visual Studio Team System User Education : Scenario Topics ) from David Chesnut
A couple of friends of mine in the Microsoft Visual Studio Team System team are doing some ground breaking
It certainly looks promising, and I am quite tired of the usual list of links.
Maybe this is overly picky of me, but I'd really like to see a working version of this new idea. From a usability point of view, I'd like to experience this new way of finding solutions. Perhaps you could pick a very small subset of topics and create a quick prototype somewhere?
I like it - it would be quicker to scan and accomplishes what you are after very well.
Here is the thing though - what if that isn't what I need? Where do I go then?
What help files need is a thesaurus which can use the words I use to map to words that the product team uses in the product until I understand all the metaphors and basic terms correctly for the product. (And once that happens I might not need help anyway).
My scenario is that I want to do something. I am pretty sure the product will do it - I just know know what the feature is actually called in the product, just the name of the concept as I am thinking about it generally.
That is by far my biggest frustration with Microsoft help files for both Visual Studio and Office.
I really like the idea. It's like user stories in agile software development. Such scenario topics are certainly useful if the user discovers them through searching or hitting F1 provided the visuals are more interactive - say, the user can click on a task and be navigated to a more orientation "How To" topic.
The visual representation can, by the way, utilize Silverlight to introduce animation and more interactivity.
Please don't do this. The existing organization and structure of your documentation is easily comprehensible and usable already. It uses a model that is familiar to anyone who has read and used a technical book with a well-crafted table of contents.
Using search on MSDN (when it works, Google is often a more effective entry point) and then selecting a topic, orients you to the organization of the MSDN Library as a whole using the hierarchical structure of the table of contents control and "breadcrumbs" within each topic.
Also realize that people do need to spend some time reading to understand and orient themselves to a subject. High quality, accurate writing cannot be replaced by pictures and terse and cryptic bullet points. Concision is valuable, but should not be an end in itself.
The example "orientation" topics you provide as bad examples, are actually more effective and comprehensible than the constructions you have created. Many of the pictures you've provided are largely superfluous and distracting. They would make much more sense if they were all contained within a single conceptual overview so that they could be related to each other. The notion that every "scenario card" should contain an illustration seems arbitrary. An illustration or diagram should serve a purpose. Complementing the written content, or providing information that is not readily explained in words. They should not be provided simply to fill a slot in a template.
Please don't waste time fooling around with the periphery of your sets of documentation. Spend more time writing thoughtful core content with usable and well-explained code samples. Take advantage of editors and knowledgeable technical reviewers to produced accurate, refined, and clear prose.
David Chesnut has posted an article asking for feedback on changing the orientation of the documentation
We rolled out scenario cards as a way to give some navigation and advance organization to our content.
We rolled out scenario cards as a way to give some navigation and advance organization to our content
In a continued bit of discovery, other teams are using a similar approach to the scenario topics we proposed
A sample help .chm file is available for download that demonstrates scenario topics. Please provide review feedback on this sample.
Last June I posted a blog entry proposing a new concept called “Scenario Topics”. (See http://blogs.msdn