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..
Problems with the Orientation Topic
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.
Introducing Scenario Topics
I’m introducing scenario topics as a better solution. The following picture shows an example.
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.
Parts of a Scenario
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.