Software Engineering, Project Management, and Effectiveness
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 ExamplesBefore 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 AssessmentsThe books are targeted at real-world problems and real-world solutions. They've been used for competitive assessments:
Book ApproachAt a high-level, you can think of the approach in five main workstreams:
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:
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:
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.
BuildingThis workstream is where we do the bulk of our solution engineering. It includes:
TestingThis workstream is about verifying the solutions from both a technical and user experience perspective. It includes:
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:
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 ConceptsI 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:
FeedbackHow 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
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 EngineeringYou can think of our approach as progressive rendering of solutions (incrementally sharing and stabilizing.)
From CodePlex to MSDNAs 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
What's one path the SDL (Security Development Life Cycle) can take to amplify impact? From my perspective, I think the key is specialization for app types and verticals. I base this on lessons learned from shaping prescriptive guidance over the years, the market trend for specialization, and what I learned doing competitive assessments. I also know the enormous difference that getting specific can make (for example, our original patterns & practices threat modeling was one-size fits all -- now we shape it based on app type. This lets us integrate more precise "building codes," patterns, and recommendations.)
Conceptual Framework / Mental ModelHere's a strawman I put together of a conceptual model to paint the possibilities.
App TypesImagine app-type specific prescriptive guidance, services, tooling, process ...
VerticalsImagine SDL for verticals ...
Key AssetsMy take on what the various parties bring to the table ...
While it requires a bit of coordination and focus in key areas, I think it's both technically feasible and would deliver a ton of customer value. The sum is better than the parts. Thoughts?
Threat Modeling is a way to identify potential security issues to help you shape your application's security design. If you need to create a threat model, and you aren't sure how, here's some links to get you started. (Note that our patterns & practices threat modeling approach is adaptable for agile scenarios. In fact, our dominant set of customers we tested our approach with were using agile methodologies. I'll cover doing agile security another day. )
This is an oldie but a goodie. Alex (from our original team) walks through our patterns & practices Security Engineering Approach. I knew the video exists, but I had a hard time finding it again so I'm posting the link here.
Key ChangesA few things have changed since our original video:
If you have to compete for resources or budget or sell an idea, one of the keys is a business case. One way to think of a business case is "how big is the pie" and "what's your slice." You use the business case either to argue for your project or in argument against other projects competing for the same resources and budget.
The Three Keys of a Business CaseBecause the business case is such a critical piece of the project puzzle, I asked one of my mentors for their take on an effective business case. Here's the keys:
The Fourth KeyMy mentor was on a roll and added an additional key:
4. Risk / reward "options." The key is to be able to chunk down the value or the risk into an acceptable size (right-size the risk.) For example "I like your idea, but it's too big a chunk to bite off."
How do you design an org? While there's lots of approaches, one of my mentors shared the 5 Ps approach with me. To think about the org, you need to enumerate the 5 Ps to define the organization, the type of talent you need, overall organizational competencies, culture, etc. If you don't know what you're trying to do, you don't know who to hire.
The Five P'sThe 5 P's are:
It's one thing to get results. It's another to articulate them. Having a way to frame results can help both for personal learning, as well as review time when you have to reflect on accomplishments.
Commitment, Results, How, Evidence, Analysis
I've found framing results by listing the commitment, the results, the how, the evidence and the analysis to be pretty effective over the years. I'm a fan of concrete examples, so here's an example:
One of the key experiences you get with Guidance Explorer (GE) is support for manual security inspections. We call them inspections versus reviews because we inspect against specific criteria. We supply you with a starter set of inspection questions, but you can tailor them or add your own.
Security Code InspectionWe use three distinct types of inspections: design, code and deployment. For this example, we'll use Guidance Explorer to do a security code inspection of an ASP.NET application.
Summary of Steps
Step 1. Create a new View. In this step, you add a new view to My Views. To do so, in GE, right-click, My Views, and add a new View. You can name your View whatever you like, but for this example, I'll name mine "Security Code Inspection."
Step 2. Add inspection questions to your view.In this step, you add relevant security inspection questions. To do so, in GE, click the patterns & practices Library, next click Security, next click Security Engineering, next click Code Inspections. Expand the ASP.NET 2.0 set of security inspection questions.
For this example, drag and drop the questions from the following categories: Input and Data Validation, Forms Authentication, and SQL Injection. This will give you a nice focused set of questions to drive your inspection.
Step 3. Save your View to Word.In this step, you save your View as a Word doc. To do so, right-click your view (e.g. "Security Code Inspection") and click Save Vew as .... Name your doc (e.g. "My Security Code Inspection.doc") and click Save.
You just built your own security code inspection set!
Extending and ExploringThere's a lot of exploring you can do and ways you can extend:
Share Your StoriesI'm sure you're bound to have stories. If you haven't done security code inspections before, you're in for a treat. Security Code Inspections are a proven practice. While the criteria and context may vary, the technique pretty much remains the same. Share your stories either in this post or send email to email@example.com.
This is a significant release for Guidance Explorer (GE). Our online "guidance store" is now hosted on MSDN. To take advantage of this, you need to download the new version of Guidance Explorer (release 20071206)
What Is the Guidance StoreOur guidance store is a catalog of reusable guidance nuggets for helping you build applications. The catalog is organized by the following:
At a high-level, you can think of the catalog as a collection of application scenarios, "building codes" and engineering practices.
What is Guidance ExplorerGuidance Explorer is a smart client application that talks to the Guidance Store over a Web service. You can use GE to create, organize and share your favorite guidance nuggets.
Key Usage ScenariosThe key usage scenarios are:
To put it another way, you can use GE to slice and dice the patterns & practices catalog, tailor the guidance, or build your own guidance.
What's New in the Latest ReleaseWhat you can expect in Guidance Explorer version 20071206:
How's that for guidance as a service? (Personally, I think the next step is relevant guidance feeds for guidance mash up scenarios.)
When you run GE the first time, let it synch for about 10 minutes. It's downloading more than 3,000 items from our catalog.
Test Driving Guidance ExplorerHere's a few of the first things to try
I created a recurring appointment in Outlook for Fridays. It's a checklist of key leadership practices from The Leadership Challenge. Each Friday, I scan this checklist and reflect on how well I've demonstrated the practices and where I need to tune for the upcoming week.
Our patterns & practices Performance Testing Guidance for Web Applications book is now available on Amazon.
Our patterns & practices Team Development with Visual Studio Team Foundation Server book is now available on Amazon.
We posted our ASP.NET 2.0 security videos, performance testing videos, and Visual Studio Team System videos to the MSDN library.
ASP.NET 2.0 Security VideosKeith Brown explains the mechanics behind some common input and data validation security issues and how to address them.
Performance Testing VideosScott Barber explains the big picture for how to approach performance testing as well as how to do workload modeling and performance reporting.
Visual Studio Team System VideosOur team takes you through key source control concepts in Team Foundation Server.
I hope we produce more videos in the coming months. I particularly like factoring "explained" videos from the "how to" videos and keeping the videos short and focused. I think we have more work to do here, but I think we've learned key lessons each time we've done a batch of videos.
It was a nice surprise to see that yesterday our patterns & practices Visual Studio Team Foundation Server Guide was among the top downloads on CodePlex.
The HMTL version of the guide is available on MSDN at http://msdn2.microsoft.com/en-us/library/bb668991.aspx.
My Related Posts
I found an interesting article about contextual decision making. "A Leader's Framework for Decision Making," an article in Harvard Business Review, is about tailoring your decision making approach based on the context. You can use the Cynefin Framework to figure out which context you're operating in, so you can choose the most effective response. The key is whether to categorize, analyze, probe or act.
Context's Characteristics The Cynefin Framework includes five context types:
Fact-based ManagementSimple and complicated are part of the ordered world. How to respond as a leader in simple and complicated scenarios:
Pattern-based LeadershipComplex and chaotic are part of the unordered world. How to respond as a leader in complex and chaotic scenarios:
I'm always on the prowl for sources of profound insight. At my leadership workshop last week, I noticed the instructor had a wealth of practical insights and distinctions that aren't common knowledge. I asked him his favorite sources of information and he listed two:
I was surprised because I had never read either before (the titles weren't appealing to me.) I picked them up this week and it looks like they're packed with lessons learned and news I can use. I think of The Economist as sharing business and organizational practices. I think of Harvard Business Review as personal development applied to the workplace. Here's a sample of some of the titles from this month's Harvard Business Review:
I'm a fan of patterns. I think of patterns simply as problem and solution pairs. I wandered by The Hogg Blog and noticed Jason's post on The Great Debate: Patterns vs Tooling. Since patterns and tooling both have their place, I think there's less of a debate and more of a gap between state of the art and state of the practice.
Why PatternsI think patterns are an efficient way to share insights. Consolidating 100's of words down into a few is pretty powerful. A pattern language is a great way to map out the terrain of a domain. I think of the pattern language as a constellation of meaningful nuggets. I think the most insighful nuggets are the ones that help you with the toughest forks in the road.
Patterns in PracticeWhile working on our security and performance guidance, our team was able to rapidly solve and share end-to-end solutions for incredibly complex application scenarios. As we worked through customer scenarios, we would pattern match against our deployment patterns and application infrastructure patterns. To put this in perspective, I remember a customer that had been prototyping a solution for six months, that we solved in ~3 hours because we had a collection of patterns to draw from. We got to a vantage point where we could solve some of the toughest architetural issues for customers in a few minutes. Looking back, I wish we had a more agile way for sharing our learnings with more customers, and I think patterns and pattern languages could have been part of the answer.
Key Usage ScenariosThere's lots of uses for patterns, but here's some examples:
Key Issues with PatternsHere's some of the issues I've run into with some patterns and repositories over the years:
Key Opportunities for PatternsI think there's more opportunity than ever for building better pattern libraries and leveraging social software scnearios and tooling opportunities. Here's some examples:
My Favorite Pattern GuidesHere's a few of the pattern guides I've found to be useful:
Yesterday, Ed helped me word a "law" that I use for important decisions and that I see show up quite a bit in a number of places. It's the law of human relevancy.
The Law of RelevancyNo matter how relevant the information is, it's more relevant with the help of the right people.
The Human ShepherdAll this law really means is that no matter how well you organize and display information, at some point, there's a glass ceiling on how much easier you can make it for somebody to find what they need. There's always a place for the human shepherd.
Usage / Examples
A StoryIn an early version of Practices Checker (a tool meant to verify your solutions against patterns & practices recommendations), we tried to figure out relevant guidance based on the type of project (Web, winForm ...), what technologies (ADO.NET, ASMX ...) you were using, ... etc. We did this automatically and generated what I considered more harm than help (it missed things that were important and created a lot of noise.) I applied the law of relevancy and argued that we'd be better off figuring out how to leverage the user's own relevancy engine and pattern-matching ability over auto-magic guesswork. We then created a tool to help smart people, rather than a "smart" tool that gets in the way.
You can build your own guide using Guidance Explorer. Guidance Explorer is a front-end browser optimized for our patterns & practices guidance store. Here's some of the usage scenarios:
Summary of Steps
Step 1. Create a new view.To create a new view, right-click My Views and click New View. Name your view.
Step 2. Add items to your view.For this example, select some items from the patterns & practices library node and drag and drop them into your view. Note that you can edit the items. Just double-click to bring up the item, then click Edit. Once you are happy with your changes then you can save to your read write libraries (such as My Library.) You can also create new items. For example, right-click My Library and click New Item. You can then add your new item to your View by dragging and dropping.
Step 3. Save your view as a Word doc.Once you are happy with items in your view, right-click the view and save it as a Word doc. Note that you can also choose to save it as HTML.
Voila! You now have your very own, custom guide.
You can now find our patterns & practices Performance Testing Guidance for Web Applications on MSDN in HTML. It's the same guidance we hosted on CodePlex. CodePlex was our channel for agile release of the guidance. Once we baked the guidance, we ported it to MSDN.
Contents at a GlanceHere's the
DownloadYou can download the patterns & practices Performance Testing Guidance for Web Applications from CodePlex.
Guidance Explorer ScenarioIf you want to tailor the guidance for your scenario, you can download Guidance Explorer from CodePlex. Using Guidance Explorer, you can create custom views by dragging and dropping the relevant guidance and then tailoring it as you see fit. You can then save your view or an item to Word or HTML
Today we posted our Performance Testing Videos to CodePlex. They're a companion set for our patterns & practices Performance Testing Guidance for Web Applications.
Video IndexHere's a list of the videos:
You can now find our patterns & practices Team Development with Visual Studio Team Foundation Server guide on MSDN in HTML. It's the same guidance we hosted on CodePlex. CodePlex was our channel for agile release. Once we baked the guidance, we ported to MSDN. For some customers, MSDN is a trusted source, so being on MSDN is important. Additionally, MSDN provides some additional hooks and channels.
Contents At a GlanceHere's the guide at a glance
Practices at a Glance
Questions and Answers
DownloadYou can download the Team Development with Visual Studio Team Foundation Server Guide from CodePlex.
Guidance Explorer ScenarioIf you want to tailor the guidance for your scenario, you can download Guidance Explorer from CodePlex. Using Guidance Explorer, you can create custom views by dragging and dropping the relevant guidance and then tailoring it as you see fit. You can then save your view or an item to Word or HTML.
I happened to glance at the MSFT stock. I took a snapshot because I thought it was make believe. Either way, it made me smile.