This project is read-only.

Guidance Explorer Overview

Download this page as a Word doc

Introduction to Guidance Explorer

Guidance Explorer is a tool that enables consumption, creation, and distribution of development guidance.

Consumption
  • You can discover relevant sets of guidelines and checklists that result in improved security and performance for your team
  • You can compose and use a discrete set of guidelines and checklists that match to the tasks you are performing on a daily basis

Creation
  • You can add new guidance to the library
  • You can modify existing guidance in the library

Distribution
  • You can share guidance with your team, your company or the community as a whole

Guidance Explorer gives a view on one more guidance libraries, each of which can contain a wide variety of guidance types.

Over the course of Guidance Explorer development and concept exploration we’ve learned that the following concepts have value for consumers of guidance as well as authors. Many of these concepts are intrinsic to Guidance Explorer, however, some are generally applicable lessons learned that can be used to improve guidance in just about any form:
  • Assigning meta-data attributes to guidance items eases discovery by enabling sort, search, and filter of guidance items
  • Content schemas and templates per guidance type result in guidance items that are more consistent to read and easier to author
  • Guidance collections that span guidance types can ease discovery
  • Modular guidance items can be easily updated due to their fine-grained scope
  • Modular guidance items allow fine-grained composition of guidance collections
  • Pre-defined collections of guidance provides a variety of useful views into a single library
  • Ability to create and share custom collections of guidance improves reusability
  • Ability to see latest guidance within any collection surfaces up-to-date guidance
  • Ability to author items and add to a collection enables customers to consolidate organization-specific guidance with Microsoft-provided guidance

This whitepaper will describe key concepts and features used by Guidance Explorer, will introduce each tool in the Guidance Explorer family, will describe the channels through which Guidance Explorer is currently distributed, will explain how guidance items are authored and published and will describe areas for future exploration.

Guidance Explorer Concepts and Features

Shared across all of the Guidance Explorer tools are the following set of important concepts and features:
  • Guidance Types
  • Metadata attributes
  • Templates and Schemas
  • Libraries
  • Views
  • Search Views
  • Guidance Sharing
  • Guidance Authoring

Guidance Types

Guidance Explorer exposes a set of pre-built guidance types out of the box:
  • Application Scenario - Provides fast before and after skeletal views of end to end application scenarios
  • Checklist Item - Series of checks you can run through to verify your design, implementation or deployment
  • Code Example - Examples that illustrate proven coding practices
  • Explained – Detailed explanation of a concept or technology
  • Guideline - What to do, why its important and how to do it
  • How To - Steps to execute an end to end task
  • Info – Quick and small informational article
  • Inspection Question – Questions you can use to improve the accuracy of design inspection, code inspection or deployment inspection
  • Patterns
    • Activity Pattern – Proven activity to solve a common engineering problem
    • Anti Pattern – Common mistakes made with proven solutions
    • Architectural Pattern – Proven architecture for common problems
    • Artifact Pattern – Description of a recurrent artifact problem and a set of proven solutions
    • Design Pattern - Proven solutions for common problems
    • Implementation Pattern - Description of a recurrent implementation problem and a set of proven solutions.
    • Pattlet - Pattlets are a pattern without the heavy schema. They are a quick description of solution to a recurring problem
  • Practice – Description of how to implement a best practice
  • Principle - The fundamental laws that underlie the guidelines
  • Question and Answer – Answer to a frequently asked questions
  • Roadmap – Overview document that gives broad guidance for an area, with links to more details
  • Technique – How to documents that walk you through the steps necessary to complete a software engineering activity
  • Test Case - How to documents that walk you through the steps necessary to test for common vulnerabilities

Additionally, Guidance Explorer allows users to create their own guidance types and expose them in the tool.

Metadata Attributes

Metadata attributes are used by Guidance Explorer to allow filtering, sorting and searching on guidance items. The following attributes are supported:
  • Rule Type – Describes the impact of this item (eg. Design, Implementation, Deployment)
  • Technology – Describes a specific technology and version this item applies to (eg. ASP.NET 2.0)
  • Topic – Describes the major area of concern this item addresses (eg. Security, Performance, Reliability)
  • Category – Describe a secondary categorization that can be used to organize the item beyond topic (eg. Caching, Input/Data Validation)
  • Authors - List all the major contributors to the item
  • Status – Describes stage of completion (eg. Beta, Release)
  • Priority – Describes relative importance of this item (eg. 1, 2, 3)

In addition to the metadata attributes the user can fill in, the item also contains the Guidance Type, the Library to which it belongs (eg. patterns & practices Library), and the guidance content as HTML.

Once items have been tagged with these attributes it becomes possible for a customer to discover guidance based on their need. For instance:
  • All Security Guidelines for ASP.NET 2.0 Forms Authentication
    1. Guidance Type == Guideline
    2. Technology == ASP.NET 2.0
    3. Topic == Security
    4. Category == Forms Authentication
  • Checklist Items for a performance code review on a .NET 2.0 application
    1. Guidance Type == Checklist Item
    2. Technology == .NET 2.0
    3. Topic == Performance
    4. Rule Type == Implementation

Templates and Schemas

Each guidance type is backed by a template which includes the content schema, descriptions of each section in the schema, and test cases to check authored content against. This template is displayed to the user when they author a new item and is available in a tab when they modify existing items. Here is an example of a template for a Guideline type:

Library

Guidance Explorer defines a library as a publishable collection of guidance. This differs from a view in that views are collections of guidance within a library. Libraries can be local or on a remote machine.

If the library is local then the guidance is stored on the local file system as a set of xml files. To update the guidance the user downloads the library (as a set of xml files) and copies it over the existing library on the file system.

If the library is remote then the user subscribes to the library. When first subscribed, all guidance in the library is copied to the local machine for browsing. All subsequent views of the guidance will check the server for a more recent copy and download just what is necessary to keep the user’s machine up to date.

View

Views are a by-reference view of guidance items within a single library or across multiple libraries.

Views can be contained within a library to show a logical collection of items for that library. For instance the patterns & practices Library has a view that contains Performance Guidelines for ASP.NET 2.0 applications.

Views can be outside of a library to show a logical collection guidance items across library boundaries. For instance a user can create a view of their favorite items contained in both the patterns & practices library as well as other libraries published from other sources.

Search View

A search view is an extension of normal views. While still a by-reference collection of guidance items, the items are selected by a query rather than by manual selection. For instance a search view could be created to select Checklist Items for a performance code review on a .NET 2.0 application.
  • Guidance Type == Checklist Item
  • Technology == .NET 2.0
  • Topic == Performance
  • Rule Type == Implementation

The benefit of a search view is that it will update with new items that match the query once they become available.

Guidance Sharing

Guidance Explorer allows users to share individual guidance items or collections of guidance in a variety of formats:
  • XML format allows items, views or libraries to be exported and imported in Guidance Explorer
  • HTML format allows items, views or libraries to be shared with others not using Guidance Explorer
  • Word doc format allows items, views or libraries to be printed and used offline

Organizations can share libraries by publishing them to a UNC or HTTP location so that team members can subscribe to them. Once subscribed the Guidance Explorer user, if connected to the network, will always see up to date content for that library. When offline, the user can view the version of the library cached on the local file system.

For more information see, “How to Publish a Guidance Library to a Network Share” in the appendix.

Guidance Authoring

Guidance Explorer allows users to author new guidance items or modify existing items. This feature is useful for a couple of reasons:
  1. The Guidance Explorer team uses it to create the Guidance Library
  2. Customers can create new items as required for their organization. For instance a customer could create coding standards in Guidance Explorer that could be viewed alongside the patterns & practices library.
  3. Customers can modify existing items as required for their organization. For instance, there may be specific instructions or caveats on a guideline that apply to the development environment in use at a customer site.

Guidance Explorer supports authoring through the following mechanisms:
  • Defined Guidance Types allows author to pick type most suitable for their needs
  • Guidance Types encourage authors to write fine grained guidance items. For example one Guideline at a time vs. creating a monolithic document that covers all Guidelines for an area of concern.
  • Templates, schemas and test cases allow an author to write guidance consistent in structure and quality

Guidance Explorer also allows users to create new guidance types. To create a new guidance type the user provides:
  • An icon that will represent the guidance type in the tree
  • A template that authors can use to create the guidance type
  • An example that authors can use to see the guidance type in action

Guidance Explorer Components

There are several tools under active development in the Guidance Explorer family. Guidance Explorer tooling and content is currently available from two locations – GotDotNet and GuidanceLibrary.com. The following table lists the tools along with a description and summary of the state of development as of 8/24/2006:

Component Description Location
GE Offline Client The thick client viewer for Guidance Library. Contains the complete set of currently implemented GE features. http://www.codeplex.com/guidanceexplorer
Guidance Explorer Authoring Toolkit The Authoring Toolkit is a stripped down version of Guidance Explorer designed for guidance authors who want to use Guidance Explorer to create and/or distribute their own guidance. http://www.codeplex.com/guidanceexplorer
GE Online Client The web client view for Guidance Library. Points at a server-side store of xml files. Contains guidance browsing features only. http://www.guidancelibrary.com/GuidanceExplorerBeta/
Guidance Library Library of guidance items. Currently an offline store of xml files. Guidance Explorer downloads items from an MSDN server
www.GuidanceLibrary.com FlexWiki site that contains a partial copy of the guidance library. Allows threaded discussion on guidance items as well as RSS feeds on collections of items. http://www.guidancelibrary.com/
Visual Studio add-in Add-in for Visual Studio 2005 that exposes all the features contained in the GE offline client. Adds features enabling guidance to be associated with a VS solution. Under development.

Future Direction

The Guidance Explorer team is actively exploring the following areas:
  • Visual Studio integration
  • Community features

Visual Studio Integration

The current Visual Studio add-in is a close match to the GE offline client both in user experience and feature-set. It adds the ability to associate guidance with a solution so that customers can create collections of guidance for their specific project needs.

Additional areas of possible exploration:
  • Code snippets
    • Expose code samples as insertable code snippets
  • Code highlighting for defects
    • Highlight code and configuration defects in the IDE as code is written and suggest quick fixes where appropriate
  • Modeling patterns
    • Expose patterns as modeling constructs that can be added to a project and associated with code
  • Project templates
    • Prescriptive guidance based on app type
  • FXCop and validators
    • Add checks that cover p&p checklist items
  • Performance tests
    • Templates to test for common performance problems
  • Manual tests
    • Templates to test for common performance and security problems
  • Automated tests
    • Templates to test for common performance and security problems

Community Features

The following are areas of potential exploration:
  • Content tagging
  • User-driven content rating
  • Aggregation of community supplied content

Appendix

How to Publish a Guidance Library to a Network Share

Guidance Explorer allows an author to create and publish guidance.

To create and publish guidance the user simply takes the following steps:
  1. Create a guidance library in Guidance Explorer
  2. Export guidance library as a set of XML files
  3. Copy files to network or http location
  4. Subscribe Guidance Explorer the new library

1. Create a Guidance Library

Add a new Library by right clicking in the Guidance Explorer tree and select New Library:
1.jpg

Create content in the library by right clicking in the tree and select New Item:
2.jpg

As guidance items are added to the library Guidance Explorer will expose guidance-type nodes for each guidance-type that you create:
3.jpg

2. Export Guidance

Export the library to any file location by right clicking on the library and select Export Library:
4.jpg

As a result the library description and all items are exported to the selected location.

3. Copy to Network Location

Browse to the file location to which you exported your guidance library:
5.jpg

Then copy the entire library to the new network or http location.
For more information on publishing to an HTTP location, see - http://channel9.msdn.com/wiki/default.aspx/GuidanceLibrary.GEFAQ011

4. Subscribe to the Library

To subscribe to the library right click on Subscribed Libraries node and select Subscribe to Library. Once you point Guidance Explorer to the remote library location it will display in Guidance Explorer within the Subscribed Libraries tree node.

Any updates to library will be shown in Guidance Explorer (new items, deleted items or updated items). Guidance Explorer will check each time it starts and each time the guidance is viewed for updates to ensure the library is up to date.

Last edited Jan 17, 2008 at 5:21 PM by jtaylorsi, version 8

Comments

Geekays Oct 31, 2008 at 10:07 AM 
I am trying to set up the Guidance Explorer online client to work with the Online store and not getting enough time to understand how it is designed to work. There is no documentation either. I shall like to know if anybody tried the same and done it so. I want my teams to share the guidance library from the online client as I don't want everybody to use the smart client solution as it takes up more administrative requirements and include hassles for management.

Please get back if anybody can help.

Regards,
Kangkan
http://www.geekays.net

dblack Mar 4, 2008 at 4:26 AM 
It would be great if the Guidance Toolkit/Explorer, FxCop, and the Framework Design Guidelines were unified in both Content as well as a Tool. In other words, the Guidance Packages should mirror the Framework Design Guidelines (plus any custom Rules/Patterns one has added) and FxCop should be the Tool used to analyze the implementation of the Guidelines and Packages. The concept of the 3 serves the same fundamental purpose - to design and implement better software. Something so important shouldn't be so cumbersome and time consuming to use 3 different resources.