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
Last June I posted a blog entry proposing a new concept called “Scenario Topics”. (See http://blogs.msdn.com/vstsue/archive/2007/06/25/scenario-topics.aspx).
The proposal was to replace orientation topics with scenario topics. Orientation topics are parent topics of a collection of related children topics in the table of contents. The concept is that a scenario topic provides a better context of what topics are under it, and how those topics most likely relate to the scenarios you are thinking about in that space. The following changes were proposed to accomplish this:
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 create 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.
Recently our team built a sample help .chm file of what this would look like. We took existing content from sections about managing work items in Microsoft Excel, and Version Control, and reworked them into scenario topics.
In addition to the changes listed in the previous list, there are two more things we added to the .chm sample.
1. Each scenario topic has a list of links at the bottom to the other scenario topics in the immediate area to aid navigation.
2. Each leaf topic under the scenario topics has a thumbnail image that links back to the parent scenario. Again, this is to aid navigation and provide context about where you are at.
I want to get your feedback on this approach. We are posting the .chm file here for your evaluation. VSTF Help Scenario Topics.chm contains the scenario topics. Please download it and review the layout of the content. Let us know what you think about the scenario topics. Are there things you like or dislike? Are there things you would change?
To download the file, right-click the attachment at the bottom of this post and save the file to a local folder. Then you will need to right-click the file and choose to "unblock" it so that it displays properly. This is a security artifact of downloading .chm files. For more information about security and unblocking .chm files, see KB902225.
You can send feedback by commenting on this blog article. Or you can send me e-mail at firstname.lastname@example.org. I look forward to hearing your discussion.
PingBack from http://geeklectures.info/2007/12/21/sample-help-file-for-scenario-topics/
Head over to the Team System User Education blog to get a look at a sample of what David Chesnut is calling
excellent idea. It would be also great to have more end to end "how to". TFS is great but I feel that it lacks really good "how to" documents.
For our next release, we’d like your feedback about how we might improve our orientation topics. These