238 New Items in Guidance Explorer

  • Article

Today we published 238 new guidance items in Guidance Explorer.  If you use the offline client, it should automatically synchronize to our online store.

We're in the process of performing a guidance sweep.  The approach to the sweep is twofold:
1.  Make existing guidance available in Guidance Explorer.
2.  Identify user experience issues with the information models and tool design.

Benefits in GE
Making existing guidance available in Guidance Explorer involves re-factoring existing security guidance and performance guidance.  The benefits of having the guidance available in Guidance Explorer include:

  • you can view across topics (for example, you can see across the security and the performance guidance)
  • you can filter down to exactly the guidance items you need for a given scenario or task
  • you can build multiple custom views based on how you need to use the guidance
  • you can build guides on the fly (you can save a view as a Word doc or HTML files for example)
  • you can tailor the guidance to your scenario (e.g. save an item into your library in GE and edit the guidance to your liking)
  • you can supplement the guidance for your scenario (because GE is also an authoring environment, you can write your own guidance)

How We Improve Our Guidance
An underlying strategy in GE was to help support users quickly hunt and gather relevant items rather than try and guess your context and what you need.  In other words, it's a tool to help smart people versus a smart tool that might get in your way.  This was actually an important decision because we had to pick a problem we knew we could help directly solve and add value.

The feedback from customers on existing guidance was that it was great stuff, but there were 3 key problems:
1.  it's a copy+paste exercise to grab just the guidance you need
2.  it's not atomic enough (monoliths over bite-sized chunks)
3.  many of the items, while they read well, were not actionable enough

That's why we took the following measures on our guidance:

  • split the guidelines and checklists into individual items (we chunked the guidance into units of action)
  • we cleaned up our templates for the various guidance types (we gave the chunked items a common look and feel)
  • made the schema explicitly include answers to "why" and "how", as well as include problem examples and solution examples (we made the chunks more actionable and verifiable)

As we port existing guidance to our updated schemas, we often find guidance items lacking key information such as why or how, or example code.

Guidance Explorer in Practice
What's been great so far is that some folks in the field have let me know how they've been using it for customer engagments.  Apparently the ability to customize guidance has resonated very well.  One consultant in particular has used Guidance Explorer for several engagements to save time and effort.  He uses GE as a general purpose rules and guidelines store.  He's also tailored guidelines and checklists for different audience levels (executive, development leads, architects, developers, PMs) and for different activities (design reviews, code reviews, and deployment reviews).

A few customers have let me know they are using the UNC share scenario to create guidance libraries for their team development.  They told me they like the idea that it is like a simple typed-wiki that you can act on.  The fact that they can create views and print out docs from the library has been the main appeal.

The other benefit that more customers are appreciating is the templates for guidelines and checklists.  They like the fact that it starts to simplify authoring as well as sharing prescriptive guidance.  For anybody who has authored guidelines or checklists, they know that it's challenging to write actionable guidance that can be reused.  What we're sharing in Guidance Explorer is the benefit of experience and lessons learned over the years of producing resuable guidance for various audiences.

R&D Project
As a reminder and to keep things in perspective, Guidance Explorer is an R&D project.  While there are immediately tangible benefits, the real focus is on the learnings around user experience so that patterns & practices can improve it's ability to author and share guidance, and to make progress on helping debottleneck the creation of prescritive guidance for the software industry.

Feedback
You can send feedback on GE directly to the team at getool@microsoft.com