Developer Guidance IA at a Glance
The Information Architecture (“IA”) for Microsoft Developer Guidance is a work in progress. You can see a living instance of the IA at Microsoft Developer Guidance Maps.
The purpose of the IA is to simplify and improve the effectiveness of content for Microsoft developer guidance. Rather than create more prescriptive guidance, our management team wants me to scale by baking what I’ve learned from building Microsoft Blue Books and platform playbooks into an Information Architecture that improves our overall content effectiveness for our developer platform. This means having me work at the “meta” level to frame out the information architecture for our content and our platform technologies.
The IA work that I’m primarily focused on is about figuring out the most effective content types, schemas, and the relationships among the content types. It’s also about figuring out technology “information models”, domain models, feature sets/capability maps, and key relationships among the technologies. As you can imagine, mapping out the content story, the Microsoft application platform story, customer scenarios, and finding a way to blend and integrate these multiple dimensions is a bit of a challenge. The payoffs can be big though. On the producer side, the potential upside is we improve our portfolio of content, while improving our processes for content, as well as improving the efficiency and effectiveness of our content. On the user side, the potential upside is that it gets easier to find and browse the information you need, in a simplified, contextual, and consumable way.
A Simple View of the IA …
Here is a simple view of how I think of an IA for Developer Guidance at a top level …
It consists of three key parts:
- App / Solution Hubs. One way to up-level information for technologies is to group the information by scenarios or solutions. For example, when you can look at the Microsoft application platform, you can think of it in terms of platform, tools, and process (i.e. the .NET Framework, Visual Studio, and ALM for example.) You can imagine creating a “solution” hub for each area. You can also imagine grouping information by application types or deployment targets. This is a loose categorization but you can think of it in terms of developers building applications for the cloud, desktop, phone, server, etc. … or you can think of it in terms of customers building Web apps, phone apps, services, etc. This is an abstraction that sits above the technology. Depending on what you want to build, you can choose the most relevant or appropriate platforms and technologies.
- Tech Hubs. These are simply “one-stop shops” for key content, documentation, and guidance for a particular product or technology. For these to be effective, it means finding and organizing the most useful content for that particular technology. In other words, rather than a stream of content, it’s an organized body of content.
- Simple IA. The simplest way I’ve found to make content useful for a given technology is to make it easy to browse by topics, by features, and by content types (Code Samples, How Tos, Videos, etc.)
Why “Hubs”? … This is simply a “Hub and Spoke” pattern, where the “Hub” is a place to bring the various spokes together.
A More Complete View of the IA …
Here is a more complete view of the IA in progress …
To explain the model, I’ll use a simple example. If you wanted to build applications for the cloud, the two main paths are building a Web application or a Web service. On the Microsoft platform, that translates to ASP.NET and WCF. Imagine that you can browse common application patterns and design patterns from the Cloud hub. Imagine that you can then explore specific Code Samples, How Tos, Videos, or Training for a specific technology, such as Windows Azure, or ASP.NET, or WCF, or that you can quickly jump into the more relevant node in the MSDN Library and explore the product documentation with ease. Further imagine that the Code Samples, How Tos, Videos, or Training are organized by topics that reflect common scenarios. Imagine that for any of the key technologies, you can easily browse the topics or the features, and find relevant content.
The easiest way to see this model in action is to browse the Microsoft Developer Guidance Maps site, where I model, prototype, and test the IA with customers. Before rolling out any IA changes, this is a way to experiment and rapidly change the model.
Key IA Components at a Glance
Here is a summary of the key Information Architecture components at a glance:
| Item | Notes |
|---|---|
| App / Solution Hubs | App Hubs are simply information hubs centered around solutions or app types. They are an abstraction from the specific technology or product. An example set of App Hubs could be:
A good App Hub makes it easy to get started, build your first app, find the key technologies, and solve the most common and important problems, as well as provides arch/design guidance, patterns, and best practices. Here is an example of an App Hub: |
| Tech Hubs | Tech Hubs are simply information hubs centered around products or technologies. They showcase the best information and sources of information for a given technology. An example set of Tech Hubs could be:
A good Tech Hub makes it easy to figure out the technology, get started, find the documentation, and browse by topics, features, and content types, including Code Samples, How Tos, Videos, and Training. Here is an example of a Tech Hub:
|
| Feature Maps | Feature Maps are simply lists of the features for a given technology. These are relatively straightforward because they are identified by product teams. The feature names are especially helpful when it comes to creating product usage guidance. Here are example Feature Maps: |
| Topic Maps | Topic Maps are simply lists of topics that represent areas or categories of scenarios. While topic maps are great for organizing scenarios, they can also organize concepts, questions, or tasks.
Here are example Topic Maps: |
| Collections by Content Type | Collections by Content Type are simply collections of content such as Code Samples, How Tos, Videos, and Training. When you organize content by content types, this helps you evaluate the ROI against the cost of a given type. It also makes it easier to innovate on experiences. For example, you can show a carousel of videos. It also makes it easier to set and meet expectations. When a user browses a How To, they come to expect a set of actionable steps to perform a task. Here are examples of browsing by content type for ASP.NET: |
| Scenario Maps | Scenario Maps are simply lists of user scenarios worded as “How to”, such as “How to show records from the database.” The Scenario Maps are generated by consulting with product teams, customers, field, industry experts, support, etc. Scenario Maps help to drive content by identifying demand. The categories of scenarios help identify the key topics for Topic Maps. Here are some example Scenario Maps: |
| Learning Roadmaps | Learning Roadmaps are simply lists of learning objectives worded as “Learn how to” or “How to” … etc. Learning Roadmaps lay out a learning path through sets of concepts and tasks for a given domain. They help identify what training assets need to be created against demand, as well as identify effective paths through concepts and tasks to quickly gain proficiency within a domain. Here is an example Learning Roadmap: |
| Content Types | Content Types are simply types of content. Identifying content types helps you make deliberate choices against what kinds of content you will invest in. For example, are books or patterns as a content type, effective for users? Here are some of the common content types used for Developer Guidance:
|
| Content Schemas | Content Schemas are simply structures for content in the form of templates. Each template identifies the content pattern. For example, How Tos include a summary, a list of objectives, a list of steps, and then each step details how to perform a sub-task in the process. Here are examples of content schemas: |
| Table of Contents (TOC) Model | A Table of Contents model is simply a canonical example of organizing top level nodes for a given product or technology within the tree of the MSDN Library. The Windows Phone TOC in the MSDN Library is a good example and includes the following key components:
|
| Controlled Vocabularies | Controlled vocabularies are simply a shared set of agreed terms. They help content producers use consistent labels for ideas and concepts and to organize information. You can also use them to help map alternative terms and words back to the main term. Here are some Controlled Vocabularies I’ve found helpful:
|
You can see these parts working together in action at Microsoft Developer Guidance Maps.