Test Our patterns and practices Guidance Explorer

  • Article

I've been relatively quiet these past few weeks, getting ready to release our patterns & practices Guidance Explorer. Guidance Explorer is a new, experimental tool from the patterns & practices team that radically changes the way you consume guidance as well as the way we create it. If you’ve felt overwhelmed looking across multiple sources for good security or performance guidance then Guidance Explorer is the tool for you. You can use one tool to access a comprehensive, up to date, collection of modular guidance that will help you with your tough development tasks and design decisions. Guidance Explorer will allow you to create and distribute a set of standard best-practices that your team can adhere to for performance and security. The project includes the tool, Guidance Explorer, and a library of guidance for developers, Guidance Library. The Guidance Library will be updated weekly, ensuring you always have the most up to date information.

What's In It For You

  • If you build software with the .NET Framework, use Guidance Explorer to find the "building codes" for the .NET technologies, in terms of security and performance. They are complimentary to FX Cop rules.
  • If you want to set development standards and best practices for your team, use Guidance Explorer views to build and then distribute your team’s standard rule-set.
  • If you author guidance for development teams, use Guidance Explorer to create guidance for your teams in a more efficient and effective way by leveraging our templates, information models, key concepts, and tooling support.

What is Guidance Explorer
Guidance Explorer is a client-side tool that lets you find, filter, and sort guidance. You can organize custom guidance collections into persistent views and share these views with others. You can also save these custom views of the guidance as indexed Word or HTML documents. You can browse guidance by source, such as the patterns & practices team. You can also browse by topic, such as security or performance, or by technology, such as ASP.NET 1.1 or ASP.NET 2.0. Within a given topic or technology, you can then browse guidance within more fine-grained categories. For example, within security, you can browse by input/data validation, authentication, authorization .. etc.

Guidance Explorer was designed to simplify the creation and distribution of custom guidance. To author guidance, Guidance Explorer, includes a simple editor that uses templates for guidance. Each template includes a schema and test cases. For example, each guideline item should include what to do, why, how, a problem example, and solution example, as well as related items and where to go for more information. We created these templates by analyzing what's working and not working from our several thousands of pages of guidance over the past several years, around security and performance.

What is Guidance Library
Guidance Library is the collection of knowledge that is viewable by Guidance Explorer. It's organized by types, such as guidelines and checklists. Each type has a specific schema and test cases against that schema to help enforce quality. The library is also organized by topics, such as security and performance. The library is extensible by design so that we can add new types and new topics that prove to be useful.

Not every type of guidance goes into the guidance library. For example, you don't use it to find monolithic guides or PDFs. The most important criteria for the modules in the library is that they are atomic units of action. They can directly be tested for relevancy. They can also be tested for the results they produce and how repeatable those results are.

How To Get Started 

  1. Join the Guidance Explorer project
  2. Download Guidance Explorer
  3. Watch the video tutorials

The key to getting started is getting the tool up and running so you can play with it, and watching the short videos (1-2 minute long) to learn the main features and usage scenarios.

Your First Experiment with Guidance Explorer
For your first test with Guidance Explorer, try creating a Word doc that has just the guidelines you want. 

To run your first experiment:

  1. Create a custom view of the guidance
  2. Save the view fo the guidance as a Word doc

How To Get Involved

  1. Join the CodeGallery workspace.  To join the workspace, sign up at the Guidance Explorer Home on Codegallery
  2. Subscribe to the RSS feeds.   To subscribe to the feeds, use the RSS buttons in each section of Guidance Explorer Home on Codegallery
  3. Participate in the newsgroups.  To participate in the newsgroups, use the Guidance Explorer Message Boards on Codegallery
  4. Provide feedback on the alias.  To do so, send email to GETOOL at Microsoft.com.

What's Next
These are some of the ideas we'd like to implement:

  • VS.NET integration
  • refactoring additional guidance (e.g. existing patterns & practices guidance such as the data access, exception management, and caching guidance)
  • New guidance types (such as "test cases", "code examples", "project patterns", "whiteboard solutions")
  • New topics (such as reliability, manageability, … etc.)
    integrating bodies of guidance and ecosystems (such as integration with product documentation)

I also hope to create a model for "Guidance Feeds", where you can subscribe to relevant guidance, as well as integrate many of the emerging social software concepts, such as allowing the network/community to rate the guidance, rate the raters and contributors, and create community-driven, shareable custom views.

About Our Team
Our core team consists of:

  • Prashant Bansode.   Prashant was a core member of my Whidbey Security Guidance Project, so he's very seasoned.   I chose him specifically because of his unmatched ability to execute, and because he is one of the best customer champions I know.  What surprised me about Prashant is his ability to not only manage his own work, but help guide others, and he really gets how to deliver incremental value.
  • Diego Gonzalez.  Diego is a coding machine.  He's also capable of bridging dreams and reality with working models.   Usually, by the time you've finished your sentence on what you'd like to see, Diego's already implementing it. 
  • Ed Jezierski.   Ed's simply brilliant.  I've never seen a more impressive mix of people focus and technical expertise.  If you can dream it up, Ed can make it happen.  If you can't dream it up, Ed can dream it up for you.  Just insert a random wish and Ed can turn it into a working prototype, and incredible slideware to match.  Ed brings to the table a ton of social software concepts and ideas around taking guidance to the next level.  I've worked with Ed for many years, but it's been a while since we've partnered up on the same project.  I look forward to many brainstorms, whiteboard sessions, and off the deep end conversations over lunch.
  • Ariel Neisen.  Ariel is a developer on the team.  Ariel works for Lagash with Diego and has been Diego's coding partner.
  • Mike Reinstein.   Mike works for Security Innovation.  He's a Web application security expert.  He not only brings security development and design experience, but strong technical writing skills that have contributed to exceptional content.
  • Paul Saitta.   Paul is previously a member of IO Active, now working for Security Innovation.  He's an expert in Web applications and white-box security audits.  He's been able to distill thousands of hours of customer audits into prescriptive guidance that illuminates common mistakes in the real world.
  • Jason Taylor.   I first met Jason during my Whidbey Security Guidance Project.  He impressed me with his ability to think on his feet, execute at a rate faster than most people can ever imagine, and his ability to distill and document expertise at a level few individuals can go.  Jason has 7 years Microsoft experience under his belt, and was one of Microsoft's first test-architects.  Now he's a V.P. for Security Innovation's security consulting group.  Aside from bringing a wealth of security experience to the table,  Jason has a lot of ideas around how to improve guidance for customers in very practical ways.

Key Links