Geeks With Blogs
Jim Lavin Its all 'bout re-use

Guidance includes so many different types of documents; Help, How-Tos, FAQs, Checklists, Code Examples, Design Patterns, and Guidelines to name just a few that coming up with a standard way to develop the needed guidance is a hard task to do from scratch. Luckily Microsoft's patterns & practices group has a tool that can simplify a lot of this for you.

The Microsoft patterns & practice's Guidance Explorer provides a one stop shop for discovering, developing and publishing high quality development guidance. The project web site is located at There you can find the latest release of the tool as well as links to existing guidance examples developed by the team.

The tool includes an editor which provides standardized templates for many of the types of guidance you may want to include in your factory. The editor also includes the ability to add custom data to each guidance item for filtering by Technology, Category, Topic and Rule Type.

How I see this tool being used is pretty simple. As part of the factory development process the guidance developer creates the various guidance items using Guidance Explorer and then exports them to HTML for inclusion into the factory contents. The factory developer then includes links to the files as part of the recipes using the <DocumentationLinks> tag. Now when ever a consumer of the factory invokes a recipe the Guidance Navigator can navigate to the document relating to the action just taken. This could be anything; a checklist of what steps need to be taken in the process; a how-to article on the use of a model just created or even code examples of how to use the library just added to the project.

Another way to apply this tool to factory development is by incorporating the web edition of the tool. It provides a read-only version of the Guidance Explorer that can utilize an on-line store allowing all of your guidance to be in one place. The web edition could be launched in a separate pane within Visual Studio to provide the full guidance library to the factory consumer as they use the factory. They can perform searches for specific topics, filter on a particular category or use the Guidance Navigation pane to browse all of the sections at their leisure.

In my opinion this is a must have tool in any factory developers toolkit, check it out.

Posted on Wednesday, September 19, 2007 12:13 PM Software Factories | Back to top

Comments on this post: Guidance Development Tools

# re: Guidance Development Tools
Requesting Gravatar...
Is this project still active? Looks like it has been almost 12 months since a new release was created (20060926). Is P&P moving away from this toolset?
Left by Aaron Kowall on Sep 19, 2007 1:40 PM

# re: Guidance Development Tools
Requesting Gravatar...

I just checked the discussion area for the site and they have nto abandoned the toolset. P&P is planning to to make another release in the near future. You can follow the progress at the following URL:

Left by Jim Lavin on Sep 19, 2007 4:51 PM

Your comment:
 (will show your gravatar)

Copyright © Jim Lavin | Powered by: