J.D. Meier's Blog : Guidance Engineering

Writing Books on Time and on Budget

J.D. Meier — Fri, 06 Feb 2009 22:47:57 GMT

One of the questions I get asked is how did we execute our patterns & practices Application Architecture Guide 2.0 project, on time and on budget? It was a six month project, during which we ....

Created a language and model for application architecture. (See Grady Booch on the Microsoft Application Architecture Guide 2.0)
Wrote a 300+ page book, the patterns & practices Application Architecture Guide 2.0 (affectionately referred to as the Microsoft Playbook for Application Architecture)
Created an Application Architecture Knowledge Base (KB), with step-by-step How Tos, videos, checklists, slides, and reusable figures.
Created a series of Pocket Guides for Application Architecture.
Created a map of the Microsoft application platform.
Created technology matrixes to organize and navigate technology decisions. (See the Presentation Technology Matrix, Data Access Technology Matrix, Workflow Technology Matrix, and Integration Technology Matrix)
Created a systematic approach for the architecture and design of applications.
Created a patterns catalog for the patterns documented by the patterns & practices team.
Formed, stormed, normed, and created a performing team. (See Wikipedia on Forming, Storming, Norming and Performing.)
Coordinated among more than 70 internal and external reviewers, across key product groups and with our field, support, and experts. (See the contributors and reviewers list.)

2 Keys to Success
We used two keys to success:

Fix time, Flex scope
Agile Guidance Engineering

Fix Time, Flex Scope
One of the most successful patterns I've used for years now is to fix time, and flex scope. The idea is to deliver incremental value and find a way to flow value along the way rather than wait for one big bang at the end. This allows you to deliver the most timely and relevant value with a healthy worklife balance. It helps reduce project risk along the way. More importantly, it helps get your stakeholders on board, by showing them results versus just trust you to the end. Scope is the best to flex because there's the least amount of precision or accuracy up front, and it enables you to respond to the market or stakeholder concerns more effectively.

Agile Guidance Engineering
This is the secret sauce. I call it Agile Guidance Engineering:

In a nutshell, Agile Guidance Engineering is about building guidance using nuggets of specific types (how tos, guidelines, checklists ... etc.) and composing them into books. The books themselves are actually an information model. The information model is designed to both structure the content as well as structure the problem domain. We vet the nuggets as we go for feedback, and we prioritize, tune, and improve them along the way.

I've used Agile Guidance Engineering successfully to build the following Microsoft patterns & practices Blue Books:

My Related Posts

Agile Architecture Method Pocket Guide

J.D. Meier — Tue, 25 Nov 2008 02:54:12 GMT

We posted our Agile Architecture Method Pocket Guide to our Application Architecture Guidance KB. This is in response to customers who expressed interest in more modular guides as a supplement to our Application Architecture Guide 2.0.

Chapters At a Glance
Here’s the chapters at a glance:

Ch 01 - Agile Architecture Method
Ch 02 - Step 1 - Identify Objectives
Ch 03 - Step 2 - Identify Key Scenarios
Ch 04 - Step 3 - Application Overview
Ch 05 - Step 4 - Key Hot Spots
Ch 06 - Step 5 - Candidate Solutions
Ch 07 - Reviewing Your Architecture
Ch 08 - Communicating Your Architecture

Download

Download the Agile Architecture Method Pocket Guide.

My Related Posts

Agile Guidance

J.D. Meier — Tue, 22 Jul 2008 19:58:11 GMT

When I ramp new folks on the team, I find it helpful to whiteboard how I build prescriptive guidance. Here's a rough picture of the process:

Examples
I've used the same process for Performance Testing Guidance, Team Development with Visual Studio Team Foundation Server, and WCF Security.

Here's a brief explanation of what happens along the way:

Design
The dominant focus here is identifying candidate problems, candidate solutions, and figuring out key risks, as well as testing paths to explore. The best outcome is a set of scenarios we can execute against.

Research - finding the right people, the right problems, and the right solutions.
Prototypes - experiment and test areas of high risk to prove the path. This can include innovating on how we build prescriptive guidance. We also use these to test with customers and get feedback on the approach.
Question Lists - building organized lists of one-liner user questions.
Task Lists - building organized lists of one-liner user tasks.
Scenario Frames - organizing scenarios into meaningful buckets. See Scenario Frame Example.
Information Models - framing out the problem space and creating useful ways to organize, share, and act on the information. See Web Services Security Frame.
Guidance Types - testing which guidance types to use (how tos, checklists, guidelines, patterns, ... etc.)

Execution
The dominant focus here is product results. It's scenario-driven. Each week we pick scenarios to execute against.

Development - building prescriptive guidance, including coding, testing, and writing.
Backlog - our backlog is a prioritized set of scenarios and guidance modules.
Iterations - picking sets of scenarios to focus development on and test against.
Refactoring - tuning and pruning the guidance to improve effectiveness. This includes breaking the content up and rewriting it. For example, a common refactoring is factoring reference information from action. We try to keep reference information in our Explained modules and action information in our How Tos.
Testing - step through the guidance against the scenario. The first pass is about making sure it works. It should be executable by a human. Next, it's about reducing friction and making sure the guidance really hits the what, why and how. We test the guidance against objectives and scenarios with acceptance criteria so we know when we're done.
Problem Repros - creating step by step examples that reproduce a given problem.
Solution Repros - creating step by step examples that reproduce a given solution.

Release
We produce a Knowledge Base (KB) of guidance modules and a guide. The guidance modules are modular and can be reused. The guide includes chapters in addition to the guidance modules. Here's examples from our WCF Security Guide:

Agile Publishing
We release our guidance modules along the way to test reactions, get feedback and reshape the approach as needed.

CodePlex - we publish our guidance modules to CodePlex so we can share early versions of the guidance and get customer feedback, as well as to test the structure of the guidance, and experiment with user experience.
Guidance Explorer - we publish guidance modules to Guidance Explorer so users can do their own guidance mash ups and build their own personalized guides. Our field also uses this to build customized sets of guidance for customers.

Stable Reference
Once we've tested and vetted the guidance and have made it through a few rounds of customer feedback, we push the guidance to MSDN.

MSDN - this is the trusted site that users expect to see our prescriptive guidance in final form.
Visual Studio/ Visual Studio Team System - once we're a part of the MSDN distribution, we can automatically take advantage of the VS/VSTS documentation integration.

My Related Posts

Software Guidance Share

J.D. Meier — Sat, 12 Jul 2008 23:19:14 GMT

I'm testing another version of the home page on Software Guidance Share. Software Guidance Share is a perpetual work in progress. I think of it as my quick-and-dirty guidance KB for developers and solution architects. I continuously refactor information into reusable nuggets. I also test ways to browse the guidance and find relationships among the nuggets.

Here's a couple of example scenarios:

I haven't fleshed out some of the areas, but the Wiki gives me a lot of flexibility and it's easy to course-correct. In other words, it's more adaptable than adapted.

Patterns and Practices for Visual Studio Team System

J.D. Meier — Fri, 29 Feb 2008 23:14:00 GMT

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:

VSTS Guidance KB (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.

Team Development with Visual Studio Team System (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:

Visual Studio Team System Prescriptive Guidance (MSDN)

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

Team Development with Visual Studio Team Foundation Server

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

Guidance Share Sweep

J.D. Meier — Wed, 02 Jan 2008 18:48:06 GMT

One of the most important things I did while I was on vacation was sweeping Guidance Share. Guidance Share is where I consolidate my body of software engineering guidance and test user experiences. I redesigned the home page for simpler browsing and findability. It was more pain than pleasure for me, but if it helps the broader community, that's my payback.

Here's a highlight of Guidance Share:

Browsable nuggets for software performance and security
Durable, evolvable frames for security and performance (think of these as maps)
How Tos, Guidelines, Checklists and more

Guidance Share gives me a unique vantage point that I haven't been able to get any other way. The act of building it and evolving it helps me make gain new insights. It also forces me to find ways to be extremely efficient. I then try to carry these lessons over to MSDN and to help shape patterns & practices information models. I don't own the MSDN experience, but I can give input. Guidance Share helps me solidify my recommendations with living proof. It's also let's me quickly experiment with new user experiences.

My biggest lesson learned is how difficult it is to integrate information and make it useful, even when you own it. It's one thing to have a snapshot of information that's useful for a given point in time; it's another to create a stable backdrop with a firm foundation that can evolve over time. The key is factoring volatile from stable information, and enabling them to play well together.

Note that Guidance Share is under construction and there are some obviously empty areas, but it's a work in progress. It's a living knowledge base for software engineering that I periodically sweep to share the best that I've learned.

Enjoy!

Building Books in patterns and practices

J.D. Meier — Tue, 25 Dec 2007 00:18:00 GMT

Book building is art and science. I've built a few books over the years at patterns & practices. In this post, I'll share a behind the scenes look at what it takes to do so. I'll save the project management piece for another day, and focus on the core of book building.

Book Examples
Before we get into the details, here's a quick look at my past books:

If you're familiar with the books, particularly Improving Web Application Security and Improving .NET Application Performance and Scalability, you'll know that the books aren't like typical books. They're optimized to be executed rather than read. The expectation is you'll use them to improve your effectiveness on the job. That's why you can get the books in the bookstore, online or in Visual Studio ... in print, PDF or HTML.

Competitive Assessments
The books are targeted at real-world problems and real-world solutions. They've been used for competitive assessments:

Book Approach
At a high-level, you can think of the approach in five main workstreams:

Researching and analysis.
Designing.
Building,
Testing.
Releasing.

It's a "test-driven" approach, meaning we start with tests (questions and tasks) that our prescriptive guidance needs to pass. The bulk of the work is building "nuggets" that can be used standalone. We then assemble an end-to-end guide. Throughout the process we verify with test cases, lab repros, internal and external reviews, both with subject matter experts and every day users.

Researching and Analysis
This workstream is about getting clarity on the problem space. It includes:

Identify the Key Resources in the Domain. This is about finding all the relevant blogs, sites, articles, code, slides ... etc. for a given domain or problem area. Here's an example of our Visual Studio Team System Resource List.
Identify the Key People in the Domain. This includes enumerating internal folks (product support, field, product teams, experts) as well as external folks (partners, MVPs, customers, experts, ... etc.)
Identify the Key Categories in the Domain. Knowing the terms in the domain, speeds up our research efforts. For example, if we know the names of the features for a product, we can quickly explore the product docs. If we know how the community is tagging the information, we can quickly parse the broader "Web community KB." Reviewing key blogosphere is a fast way to figure out the folksonomy that people use. This helps us build information models for the space.
Identify the Key Questions, Tasks, and Scenarios. This is a process of making tickler lists of the questions that users ask, the tasks they perform and the key scenarios.
Identify Key Contributors. This includes finding folks that want to participate and actually create content. A lot of folks raise their hands, but only a few deliver. That's the nature of the beast.
Identify Key Reviewers. Finding reviewers is pretty easy since lots of folks want to steer. The trick is finding the folks that inject insights and dramatically raise the quality of the guidance. We cherish our key reviewers.
Identify Key Reference Examples. This is about gathering all the working examples we know of from support, field, and customers. I like to be able to point to working instances of the guidance in practice. I also like to reverse engineer success (success leaves clues.)
Build data points. If you're into information, these would rock your world. These are dense collections of insights that we share among the team. Sometimes we use a Wiki, but we always use Word docs to capture and share them, since they get are very dense and we track the sources of the information.

For more information on researching, see my related posts: Analyzing a Problem Space and How To Research Efficiently.

Designing
This workstream is an iterative process of spiraling down on solutions. It includes:

Create a scenario frame. This is where we frame out the guidance. It includes organizing scenarios into key categories and sub-categories. This is where the folksonomy and information models helps. Here's examples of our Visual Studio Scenario Frames.
Review the scenario frame. This is painful but rewarding. We review the scenario frames with customers and experts, internally and externally. It's a spiral down process.
Identify the priorities. Once we have scenario frames and we've spent the time reviewing, we're at a great vantage point to separate the forest from the trees. One technique we use to prioritize is we ask product team members to think of the top 10 issues they'd like to make go away from their inbox ;)
Identify candidate nugget types and titles. This is where we figure out whether something should be a "How To" set of steps or an "Explained" articles, such as an explanation of how something works or it's intended usage patterns. We hammer on the titles so that they both represent compelling information, they set the right expectations, and they are more findable on the Web.
Identify the objectives for each nugget. We identify the key "tests for success" in each nugget, by listing the specific tasks, questions or objectives you'll accomplish by using that particular nugget. For an example, see the "Objectives" section in How To Protect from Injection Attacks in ASP.NET.
Prototype the Table of Contents (TOC.) I do this on the whiteboard and paint the broad strokes first. I factor the guide into two main parts: a fast path through the key strategies and concepts, and an actionable reference of nuggets (principles, patterns and practices.) I also come up with a story I can tell in the hall. For example, the story behind Improving Web Application Security was "how to build a hack proof app." That set the stage and kept things on track when things got complex (as they always do.)
Create conceptual frameworks. This involves figuring out the most effective ways to look at and tackle the problem space. For examples, see Performance Fast Track and Security Fast Track.

For more information, see my related posts: Guidance 2.0, Scenarios in Practice, Scenario Frames for Guidance, and Driver's Guide vs. Owner's Manual.

Building
This workstream is where we do the bulk of our solution engineering. It includes:

Prototype nuggets. This is where we frame out and create skeletal examples of nuggets. We incrementally render the final nugget by adding information and details as we learn, build, and test.
Create problem repros. Reproducing problems helps to both understand the problem space as well as make it easier to share the problems and get more eyes on them. We also need to be able to test the solutions against the problems. We typically capture problem repros in notepad.
Create solution repros. This is where we create the leanest, stripped down example of solving the problem. We capture these as steps in notepad, including copy+pastable code or configuration steps as needed. Each person on the team should be able to quickly run through the solution repro. This helps us find the sticking spots and reduce the friction.
Create key figures. This is a painful process. The goal is find the fastest way to convey the information visually. I think my favorite all time examples are our "cartoons" for showing our security scenarios and solutions.
Write nuggets. This involves fleshing out the details. I try to keep the text as tight as possible throughout the process. It's more work to make it dense, but it pays off where we spend the time.
Write chapters. This is similar to writing the nuggets but from a zoom level this is where it's about showing the forest.
Modify the TOC. This is a continuous process. As we learn more about the space, it gets easier to organize the chapters and nuggets into parts and a story that we can stand behind.
Refactor nuggets and chapters. For an example TOC, see the Landing Page for Improving Web Application Security.

Testing
This workstream is about verifying the solutions from both a technical and user experience perspective. It includes:

Test solutions in the lab. Since the bulk of our books are executable, it's fairly straightforward to test the solutions to make sure they work in the lab. Scenario and scoping is important, so this is where our scenario frames and objectives for each nugget really help.
Test solutions in the field. This is where we try to find customers that share the problems we've solved and put our solutions into practice. Usually, this involves leveraging our field or product support that acts as a proxy for the customer. We also have a few customers running alongside us that can help test in their scenarios.
Dog Fooding. One rule I have on our team is eating our own dog food so we have first hand experience with the usability of the guidance and can directly use it to solve problems. See Eating One's Own Dog Food on Wikipedia.
Review solutions. This includes reviews from internal and external stakeholders. We do this incrementally. First our immediate team has to approve, next our immediate key contributors and reviewers (the ones that have more bandwidth and commitment) and then more broadly (such as on CodePlex.) For an example of the sets of reviewers, see the Landing Page for Improving .NET Application Performance and Scalability.
Improve solutions. Rather than just focus on finding issues or proving that something technically works, it's about raising the bar in terms of user experience, or finding a more effective technique or solution. We use Timeboxing to help scope. See How To Use Time Boxing for Getting Results.

For more information, see my related post: Test-Driven Guidance.

Release
This workstream is about making the guidance customer available. It's incremental, iterative and we stabilize over time. it includes:

Create an online community KB. This is where we create an online site to share the nuggets. For an example, see our Visual Studio Team System Online Community KB on CodePlex. By sharing the nuggets here, we can test and vet before baking into more durable form factors such as the PDF and print versions.
Create a PDF. We do this once we've stabilized enough that the PDF is a good example, of what the final book will be. While details may change, the overall frame is durable and we use the PDF as a simple way to share the book before we're baked. For an example PDF, see patterns & practices Team Development with Visual Studio Team Foundation Server.
Create the book. This includes creating a fit and finish PDF, as well as creating print-quality graphics, and coordinating with our MS Press team to create the final print versions of the book, as well as getting the book on the shelf.
Port to MSDN. We port the guidance to a MSDN so that we get better reach and because customers expect it there. In the ideal scenario, we host the PDF and HTML, as well as have a print version.

Keep in mind that it's a stabilization process over time of various form factors and channels. We do our agile guidance on CodePlex, then stabilize and port to MSDN and a book when we're baked. For more information, see my related post CodePlex, GE and MSDN.

Key Concepts
I walked through the process first so that you have a good idea of the end-to-end approach. Here I'll highlight some of the key concepts that underlie my approach:

Solution Engineering. This captures the heart of what we do. Rather than "writing a book", we're really engineering solutions for problems. That's why the team includes architects, testers, developers ... etc.
Question-Driven. I'm a fan of using questions to prioritize, drive the scope, and figure out when we're done. I know we're done when we've addressed enough of the right questions.
Principles, Patterns, and Practices. The bulk of the book is a collection of principle-based recommendations. Although we don't always formally write up patterns or name the patterns, each book contains pattern-based solutions.
Life Cycle Approach. I find using a life cycle makes the solution stronger. If I just give you technical guidance, that only helps you so far. If I give you a system for results, it changes the game.
Test-Driven. I'm a fan of using explicit test cases for content. See Test-Driven Guidance.
Conceptual Frameworks. This is the backbone of the guides. This is where innovation happens the most. These are mental models, lenses and perspectives, and systems for results. For an example, see Fast Track - A Guide for Getting Started and Applying the Guidance.
Scenario-Based Approach. You can't do a design review in a vacuum. We use scenarios to evaluate against.
Scenario Frames. Scenario Frames are organized sets of usage scenarios. We use these to frame out the problem space. See Scenario Frames for Guidance.
Executable Content. Use the content to execute your tasks.
Action vs. Reference. One key to building executable content is factoring reference information from action.
Guidance Types. Another key to building executable content, is using specific guidance types. For "reference" information, we use "Explained" nuggets. For "action" information, we use "How Tos", "Checklists" ... etc. Our guidance nugget types include: App Scenarios, At a Glance, Checklist Items, Code Examples, Explained, Guidelines, How Tos, Inspection Questions, Patterns, Practices, Principles, Roadmaps, Techniques, and Test Cases. You can browse these collections using patterns & practices Guidance Explorer.
Context-Precision. This is a term I coined to get more specific about the scenario. This improves both the modularity of our nuggets as well as the usability. Rather than a single nugget spread over many contexts, we factor and use precision. This avoid a spaghetti problem and helps reusability and maintainability. See Context-Precision.
Holistic Over Piecemeal. The guides are meant to get you up and running. The example I use is teaching you to drive. I show you how to forward, reverse, steer, brake, shift to get you going and then drill into shifting or braking as needed, rather than show you how to go forward today, then how to reverse another day, and some day how to steer. This means compressing and distilling knowledge that's been spread out over time and space.
User Effectiveness Over User Sat. To do my job well, I focus on customer effectiveness over customer satisfaction. Ideally, it's both, but there's a lot of FUD in our industry and satisfaction is very subjective. I find it more reliable to focus on measuring and testing customer effectiveness.
Criteria for Effectiveness. Part of what makes this successful is having criteria for the guidance which includes: Compliance with proven practice, complexity, quality, user competence and time to implement.
Incremental Adoption. Each guide is designed to be incrementally adopted. While the sum is better than the parts, I can't ignore the reality that incremental adoption is more likely than monolithic adoption. That's why the guides can be read end-to-end, or just grab the parts you need.
What To Do, Why, and How. While this pattern directly applies to writing prescriptive guidelines, it really exemplifies the overall guide. Rather than lose you in endless enumerations of options, you should be able to quickly figure out what to do, why, and how throughout the guide.
Entry Points. How does a user find the specific guidance they're looking for? I tend to focus on "question-based" entry points and "task-based" entry points. You're either asking a question or trying to figure out how to do something. For an example of question-based entry points, see VSTS Source Control Questions and Answers. For an example of task-based entry points, see ASP.NET 2.0 Security Practices at a Glance.
Team Guidance. Few problems can withstand sustained thinking. No problem can withstand sustained collective thinking. To get an idea of the team-based approach, see the list of contributors and reviewers at the bottom of the Landing Page for Improving .NET Application Performance and Scalability.
Customer-Connected Engineering. Simply put, this means involving customers throughout the process. How would we know we have the right problems or the right solutions without involving the people it's for?

Feedback
How do you build books? If you have thoughts, questions or feedback on my book building approach, feel free to share them here or drop me a mail. While this approach has been proven effective over time, there's always room for improvement. I'd like to hear what works for you. If you're a fellow book builder, please share your approach.

My Related Posts

CodePlex, GE, and MSDN

J.D. Meier — Fri, 21 Dec 2007 06:18:13 GMT

One of the questions I get is how we build and publish our guides and what's the relationship of CodePlex, GE and MSDN. At a high-level, we build reusable guidance nuggets for customer questions and tasks. We then build a larger guide to bring the nuggets together into a story. Together, this gives us both a knowledge base of nuggets and a series of guides. We can incrementally deliver value, refactor as appropriate, and respond to changing needs.

Bird's-Eye View of Agile Guidance Engineering
You can think of our approach as progressive rendering of solutions (incrementally sharing and stabilizing.)

From CodePlex to MSDN
As we build guidance modules, we publish them to GE and CodePlex. GE lets you, the user, build more relevant views or tailor the nuggets to your own needs. CodePlex gives us a place to experiment with views and get direct user feedback, while we vet the guidance.

Once we're stable, we do a focused, batch effort to port to MSDN. MSDN gives us a bunch more channels and hooks including integration in Visual Studio / Visual Studio Team System.

There's much more to the story, so if there's interest, I'll share a behind the scenes look at how we build books.

My Related Posts

Scenarios in Practice

J.D. Meier — Mon, 15 Oct 2007 05:21:00 GMT

Scenarios are a practical way to organize and focus your product design, development and release. (We use scenario-driven engineering in patterns & practices)

Key Benefits

Business value. You can use scenarios to evaluate business value. What pain does that scenario address? ... What opportunity does it create? ... etc.
Chunking and prioritizing. You can use scenarios to chunk up and prioritize your product. You can think of versioning in terms of releasing incremental value or scenarios.
Effective design. Walking through a set of customers scenarios and "what ifs" will help you figure out your product's most effective design. It's not a silver-bullet, but it does help make requirements more concrete, or at least put them in perspective. It also opens the door to more precise questions about user experience or engineering challenges..
Focal point for perspectives. You can use scenarios as a focal point for user experience, business and tech perspectives.
Requirements in context. You can use scenarios to put requirements in context. A requirement makes a lot more sense when you see it in action.
Architectural trade-offs. You can use scenarios to evaluate and make architectural trade-offs. You can't evaluate an architecture in a vacuum; you can evaluate against concrete scenarios. There's several flavors of scenario-based evaluations you can leverage.
Customer value. Your customers can appreciate how well you did (or didn't) address their scenario.
Tests for success. You can use scenarios as tests for success. By measuring customer effectiveness against specific scenarios, you have a way to focus your improvements.

Chunking Up a Project Using Scenarios
If you think of your product as helping a user accomplish a goal, it helps cut through the fog. You can think of your product in terms of a list of user goals, business goals and technical goals. What's the minimum set of tasks your user needs to perform with your product? That's your baseline release. What's the incremental value from there? That's how you start to shape your versions and releases.

User Experience, Business and Technical Perspectives
Using scenarios is a good forcing function to bring together the user experience, business, and technical perspectives. For the sake of example, let's say your scenario is "User views the product catalog." From the user experience perspective, you're thinking in terms of "show me a relevant list" and "don't make me wait," From a business perspective, you're thinking in terms of "support a given number of orders per hour" and "lower the total cost of ownership." From a technical standpoint, you're thinking in terms of "requests per second," "minimize resource utilization," ... etc. Well, no wonder getting software right is tough! Luckily, scenarios help you bring together and rationalize the perspectives against a common frame of reference.

Constraints Make More Sense In Context
Constraints are boundaries to operate within, or what the solution must or must not do. In software, I see a lot of generic constraints passed down as policies. When policy meets scenario, you now have a way to evaluate the effectiveness of that constraint. You can also measure whether that scenario is actually meeting the constraint. You can perform scenario-based testing against a set of scenarios with specific constraints.

Walking the Scenarios
Have you ever been sold on a great set of features, only to fall flat when you try to actually do something useful? Obviously, that's the extreme case, but it happens to me. It happens less now because whenever I go to buy something, I walk my usage scenarios. Doing a dry run against a scenario is very revealing. This approach works great on the engineering side too. It's one thing to have generic technical requirements for security or performance. It's another to evaluate a scenario and make appropriate and relevant trade-offs from a user, business and technical perspective. Suddenly, generic technical requirements no longer seem as helpful, do they? They still have their place, but when you're engineering your job is to make the right trade-offs.

Scenarios and Solutions
Given part of my job is to improve customer effectiveness on our platform, I regularly use scenarios as a backdrop for evaluation. As I've gotten more effective, I noticed shifting from features and components to scenarios and solutions is the key.

More Information

My Related Posts

How To Research Efficiently

J.D. Meier — Mon, 28 May 2007 07:51:00 GMT

Building guidance takes a lot of research. Over the years, I've learned how to do this faster and easier. One of the most important things I do is setup my folders (whether file system or Groove)

Initial Folders

/Project X
	/Drafts
	/Research
	/Reference

Folder Over Time
Over time, this ends up looking more like

Project X
	/Builds
		/2007_05_26
		/2007_05_27
	/Drafts
	/Reference
		/Articles
		/Blogs
		/Bugs
		/CaseStudies
		/Docs
		/Slides
		/Source X
		/Source Y
		/Source Z
	/Research
		/Braindumps
		/DataPoints
		/QuestionsLists
		/Topic X
		/Topic Y
		/Topix Z
	/Tests
		/Tests X
		/Tests Y
		/Tests Z
	/Whiteboards
		/Topic X
		/Topic Y
		/Topic Z

Key Points

Factor reference from research. Reference is stuff I pull in from various sources, such as slides, blogs, articles ... etc. Research holds the notes and docs I create. This way I avoid mixing information I create with information that I reference. Having a place to store my reference information helps me optimize when I'm hunting and gathering resources in batch mode. I also find that it saves me time when I have to go back and figure out where information came from.
Factor stages of information. In my basic workflow, I move information from research to drafts to builds. (where builds are guides) Keeping them separate makes it very easy for me to know the current state of the information and it gives me a safe place to re-factor and make changes. Research is effectively my sandbox to create documents and organize my notes as I see fit. Drafts is where I have to make decision on what and how to share the information. Builds is where I produce a shareable set of information.
Have a place for whiteboard captures. Whiteboards is where I dump pics from whiteboarding sessions. I'm a fan of doing braindumps at the whiteboard and quickly dumping to a place to reference. If it's just text, I write it down. If it's visual, I take a pic and file it.

I use this approach whether I'm doing personal learning or building 1200+ page guides. This approach helps me spend more time researching and less time figuring out where to put the information.

My Related Posts

Driver's Guide vs. Owner's Manual

J.D. Meier — Sun, 18 Mar 2007 02:55:00 GMT

One of the metaphors I use to explain the distinction between documentation and guidance is Driver's guide vs. Owner's Manual. While I could go into the finer details, it's a good starting point. From an owner's manual, I expect to see how things work and how they're intended to be used. From a driver's guide, I expect "how to get the most out of it."

I see the two bodies of information as very complimentary. I also see them as distinct. I wouldn't want to mix my driver's guide with my owner's manual. However, I do want to be able to seamlessly go from one to the other, when I need to. I also want my owner's manual written by the people that built it and I want my driver's guide written by the people who use it in action.

In practice, I use my owner's manual when I care and tune my RV. When I take a cross country trip, I use my driver's guide. Knowing this distinction helps me choose the right tool (information set) for the job, as well as set my expectations about the type of information I'll find.

I think finding the right metaphors is important because it helps illustrate a distinction that's not always obvious or hard to explain. I don't think guidance is yet a pervasive part of our technical landscape, and yet I see it as a key differentiator between success and failure. By pervasive, I mean I can use any product or technology and easily find the driver's guide. I mostly see owner's manuals.

Guidance 2.0

J.D. Meier — Sun, 04 Mar 2007 02:51:00 GMT

Imagine what a Guidance 2.0 world might be like ...

browse tag clouds of reusable "architecture nuggets"
subscribe to "guidance feeds" that give you the latest practices and recommendations
share your "guidance" playlists with friends (share your favorite collections of how tos, guidelines, checklists)
build guidance mashups from your favorite trusted sources of information
rate the guidance and rate the raters (think Amazon or EBay)
browse a federation of guidance Wikis in your company and in the community

I think next-gen guidance is about bringing together a lot of key concepts:

context-precision (using context to organize information)
personalization (create your own views, tailor it for your needs, ... etc.)
community type ratings (expose the thinking and rate the raters for the guidance)
guidance types (evolvable schemas for guidance types, such as how tos, guidelines, checklists, patterns ...)
Folksonomy over taxonomy

A lot of today's guidance lives in blogs. Part of the problem (and beauty) of blogs is that every end node is a blob of information. What if there were RSS end nodes that contained "collections" or "lists" of how tos, guidelines, patterns ... etc.? From a very practical standpoint, I would love to subscribe to the latest MS (or any company) recommendations and view those in a type of my choice (patterns, guidelines, how tos ... etc.) The mashupability is endless.

Those are the ideas that drove and shaped Guidance Explorer. Guidance Explorer was just one small step towards a world of more effective and efficient guidance.

Scenario Frames for Guidance

J.D. Meier — Thu, 22 Feb 2007 10:26:00 GMT

When I tackle a problem domain, I first frame out the space. To do this, I list out scenarios and sub-scenarios. I group the scenarios under categories. Sometimes categories come first, sometimes scenarios do. I call the result, a Scenario Frame.

I use Scenario Frames to evaluate platform, tools, and guidance. I also use them for product design, innovation, competitive assessments, subject matter expert reviews, arch and design reviews, and as a way to build shared understanding of a problem space.

Here's a Scenario Frame Example my team is creating to enumerate and evaluate Source Control scenarios in VSTS 2005:

What's your favorite tool for framing out problem spaces?

Context is Key

J.D. Meier — Fri, 12 Jan 2007 06:33:00 GMT

I was browsing Rico's blog and I came across his post Do Performance Analysis in Context. I couldn't agree more. When it comes to evaluation, context is key. If you don't know the scenarios and context, you can't trust the merits of your data or solutions. To spread the idea and importance at work, I've coined the term Context-Precision.

Analyzing a Problem Space

J.D. Meier — Fri, 12 Jan 2007 05:07:00 GMT

How do you learn a problem space? I've had to chunk up problem spaces to give advice for the last several years, so I've refined my approach over time. In fact, When I find myself churning or don't have the best answers, I usually find that I've missed an important step.

Problem Domain Analysis

What are the best sources of information?
What are the key questions for this problem space?
What are the key buckets or categories in this problem space?
What are the possible answers for the key questions?
What are the empirical results to draw from?
Who can be my sounding board?
What are the best answers for the key questions?

1. What are the best sources of information?
Finding the best sources of information is key to saving time. I cast a wide net then quickly spiral down to find the critical, trusted sources of information in terms of people, blogs, sites, aliases, forums, ... etc. Sources are effectively the key nodes in my knowledge network.

2. What are the key questions for this problem space?
Identifying the questions is potentially the most crucial step. If I'm not getting the right answers, I'm not asking the right questions. Questions also focus the mind, and no problem withstands sustained thinking (thinking is simply asking and answering questions).

3. What are the key buckets or categories in this problem space?
It's not long before questions start to fall into significant buckets or categories. I think of these categories as a frame of reference for the problem space. This is how we created our "Security Frame" for simplifying how we analyzed application security.

4. What are the possible answers for the key questions?
When identifying the answers, the first step is simply identifying how it's been solved before. I always like to know if this problem is new and if not, what are the ways it's been solved (the patterns). If I think I have a novel problem, I usually haven't looked hard enough. I ask myself who else would have this problem, and I don't limit myself to the software industry. For example, I've found great insights for project management and for storyboarding software solutions by borrowing from the movie industry.

One pitfall to avoid is that just because a solution worked in one case doesn't mean it's right for you. The biggest differences are usually context. I try to find the "why" and "when" behind the solution, so that I can understand what's relevant for me, as well as tailor it as necessary. When I'm given blanket advice, I'm particularly curious what's beneath the blanket.

5. What are the empirical results to draw from?
Nothing beats empirical results. Specifically I mean reference examples. Reference examples are short-cuts for success. Success leaves clues. I try to find the case studies and the people behind them. This way I can model from their success and learn from their failure (failure is just another lesson in how not to do something).

6. Who can be my sounding board?
One assumption I make when solving a problem is that there's always somebody better than me for that problem. So I then ask, well who is that and I seek them out. It's a chance to learn from the best and force me to grow my network. This is also how I build up a sounding board of experts. A sounding board is simply a set of people I trust to have useful perspective on a problem, even if it's nothing more than improving my own questions.

7. What are the best answers for the key questions?
The answers that I value the most are the principles. These are my gems. A prinicple is simply a fundamental law. I'd rather know a single priniciple, then a bunch of rules. By knowing a single principle, I can solve many variations of a problem.

Now, while I've left some details out, I've hopefully highlighted enough for you here that you find something you can use in your own problem domain analysis.