J.D. Meier's Blog

Software Engineering, Project Management, and Effectiveness

From Guides to Guidance Modules

From Guides to Guidance Modules

  • Comments 4

Have you noticed the transition from guides to guidance modules over time?  My first few guidance projects were actually guides:

While the chapters in the guides were modular, the overall outcome was an end-to-end guide.  On the upside, there was a lot of cohesion among the chapters.  On the downside, the guides were overwhelming for many customers who just wanted bits and pieces of the information.  That's the challenge of making a full guide available in html, pdf and print.

Examples of Guidance Modules
.NET 2.0 Security Guidance was the first project to use "Guidance Modules".  Guidance Modules are effectively modular types of guidance:

Benefits of Guidance Modules
The benefits of modules include:

  • "right-size" the solution to the problem
  • easier to author and test the guidance (templates and test cases)
  • easier to consume (you can grab just the guidance you need)
  • release as we go vs. wait until the end
  • you can build guides and books from the modules (strong building blocks for guides)

The Chunking Has Just Begun
While the initial chunking of guidance has certainly helped, there's more to go.  Customers have asked for even smaller chunks.  For example, rather than have all the guidelines in a single module, chunk each guideline into its own page.

Dealing with Chunks
Chunking up the guidance creates new challenges.  How do you find, gather and organize the right set of modules for your scenario?  This is a good problem to have.  Assuming there's guidance modules that have great community around them and they're prescriptive in nature (it prescribes vs. describes solutions), then the next step is to improve how you can leverage the modular information.  That's where Guidance Explorer comes in.  It was an experiment to explore new ways of creating, finding, and using guidance modules.  We learned a great deal about user experience, which I'll share in a future post.

  • One of the questions I get is how we build and publish our guides and what's the relationship of CodePlex

  • One of the questions I get is how we build and publish our guides and what's the relationship of

  • Book building is art and science. I've built a few books over the years at patterns & practices.

  • I thought it might be helpful to walk through a deliverable so you can see my current approach for building

Page 1 of 1 (4 items)