Patterns and Practices for Visual Studio Team System

  • Article

I thought it might be helpful to walk through a deliverable so you can see my current approach for building prescriptive guidance in patterns & practices.

Stage 1: Knowledge Base
We start by building the knowledge base:

In this stage, we do a lot of solution engineering.  This includes framing out the problem space using Scenario Frames.  After all, you can't fix a problem if you don't know what it is, and you don't know when you're done, if you don't know what good looks like.  It also includes creating repros for problems and solutions.  I think of this as Test-Driven Guidance. 

At this stage, we create what I call "guidance modules."   These are focused nuggets.  At a high-level, we factor reference from action.  Our key types include guidelines, checklist, how-tos, and practices.  I think Weinberg's term, the Fieldstone Method, applies to what we do.  

We also publish our modules to Guidance Explorer at this point so you can build your own guide on the fly.

Stage 2: The Guide
At this stage, we build the guide.

The guide helps put the story together.  The guide is divided into roughly two parts.  The first part is a series of fast-paced chapters that paint the broad strokes and highlight key concepts.  The second part is the hard-core reference section.  This gives us a combination of top-down and bottom up.

We share the guide in HTML and PDF.  This ways it's easy to share URLs and play in the community, or download and read the guide offline.

Stage 3: MSDN
At this stage, we port the guidance to MSDN:

Stage 4: Amazon
At this stage, we partner with Microsoft Press and we bake the printed book:

Team Guidance
One of the things you'll notice about the guides is the breadth of participation.  I'm a fan of integrating customer perspective, product perspective, field perspective, and expert perspective.  I think the best way is to involve key folks that represent those perspective.  Here's an example of the contributors and reviewers for the TFS guide.   For a more extreme example, see the team behind our Threats and Countermeasures Security Guide.

Measuring Success
At the end of the day, I measure success of the guides based on how well they improve your effectiveness.  I think our best guides improve your confidence and competence.  As much as I'd like you to enjoy reading the guides, I assume you're reading the guides to get your job done.  That's why they are dense with insight and action.

Why Guides?
Not everybody is a fan of the guides.  Personally, I see them as a way to share expertise.  You don't get the benefit of working alongside all the product team members, the field, our various customers, subject matter experts, ... etc.  That's what the guide is for.  It's a way to consolidate and share the expertise.  While they won't solve your every problem, you don't have to start from scratch.  I think the best guides help you bootstrap your success and avoid reinventing wheels.  Why go it alone, when you can stand on the shoulders of giants and learn from what works?

Related Guides

Key tips -- if you want to become a security and performance expert, learn the principles, patterns and practices for security and performance from Improving .NET Application Performance and Scalability and Improving Web Application Security.

My Related Posts