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 http://www.codeplex.com/guidanceExplorer. 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.