Mariano Szklanny’s Blog

Back in July, I posted about the documentation shipped with the first release of the Composite Application Guidance for WPF (aka Prism). Some months ago, the docs have been presented in book format:

(more details | PDF version)

Recently, I have been notified that the Japanese version is also available:

This is great news - way to go patterns & practices team!

As you may already now, the Composite Application Guidance for WPF was released a few days ago. In this project I had the pleasure of working with the patterns & practices team, mainly as a technical writer. (I wrote a few lines of code too, but nothing compared to the huge job done by devs!)

Hands On Lab for free

One of the things I want to highlight is that, apart from having 300 printed pages (!), the documentation includes a Hands on Lab. What I like about Hands on Labs is that they provide a guided and integrated learning process through practical exercises surrounded by background technical content.

The Lab is quite hidden in the table of contents; you can find it under the node Composite Application Guidance for WPF Hands On Lab in the table of contents.

Covered Topics

This lab covers the basic concepts of the Composite Application Guidance for WPF as you build a simple Hello World application. The following is a list of questions we tried to address:

• What an application based on the Composite Application Library is
• What are the Composite Application Library assemblies, what they contain
• What is the Shell project and the Shell window
• What is the Bootstrapper, and what is the UnityBootstrapper class and how it is used
• What is a container and how it relates to the dependency injection pattern
• What is a service
• What is a region
• What type of regions are supported out-of-the-box by the Composite Application Library
• What is a module
• What is the module initializer class
• What folders a module typically contains
• What are the different ways of loading modules
• What is the StaticModuleEnumerator class and how it is used
• What is a view
• What is the Region manager and how to use it to add views and named views

Topics not Covered

To keep the Lab simple (and to ship on time!), we consciously kept some topics out of the Lab. However, you can find information about those topics across the documentation. The following list presents some of the topics not covered in the Lab and links to related resources:

• Commands
• Decoupled Events
• How to dynamically load modules
• Scoped Regions.
• Presentation Model and Supervising Controller patterns
• How to unit test an application based on the Composite Application Library. See the source code in the Stock Trader Reference Implementation or in the QuickStarts.

Feedback Welcome

We didn’t include Hands On Labs in previous deliverables like the Smart Client Software Factory and the Web Client Software Factory, so we are experimenting a new approach here (we did released Hands on Lab as separate downloads some time after the official releases, though). I personally think that including a Hands On Lab within the initial package will help users with the learning process and adoption, but I’m excited about reading your comments.

Do you like the lab? Is it useful? Would you recommend it to your colleagues and/or customers? It is great to receive feedback like this, but negative feedback is welcome too!

As Blaine already announced, we have published the Web Client Software Factory documentation on MSDN. After so much work spent on the docs, it is great to see them standing there. I hope it will help users find what they need quickly, and to evaluate the factory’s content before downloading it.

Much has been mentioned about the new features the WC-SF February 2008 release includes. However, there is no much detail about what has changed as far as documentation is concerned. Since I was part of the docs team for the factory and the bundles, I thought that sharing some thoughts with the community could be a good idea.

So What is New?

Most of the efforts in the February 2008 release -regarding documentation- were targeted to include the bundles’ documentation within the factory’s documentation. This was an interesting challenge because the documentation was already large, and bringing in more content implied that it would grow even more, potentially making it harder to digest. Moreover, we wanted to stick to what we have learnt from previous releases and that we verified with the bundles: for most users, small packages of guidance are easier to read and understand than a large set of documents.

The approach we followed this time was somewhat innovative (we didn’t do this neither in SC-SF nor in previous releases of WC-SF). On one hand, we decided to bring in the bundles docs as individual guidance sections that could be read integrally and that would provide value by themselves, keeping the reader focused on the specific technical concept she/he wants to learn. This way, for example, if you want to learn about validation you know you will reach all the validation-related topics from within the Validation Guidance section.

You will find these individual guidance sections inside the new Technical Concepts node. The sections basically map one to one with bundles. They are:

• Modularity Guidance
• Validation Guidance
• Search Guidance
• Autocomplete Guidance
• Views Testability Guidance (MVP)

On the other hand, (and here comes the innovative part) we duplicated topics across the documentation. For example, the Model-View-Presenter topic can be found within the Views Testability Guidance section, and within the Patterns for Web Client Applications section. By doing this, we allow users searching for Web development patterns to discover this topic, and we allow users looking for views testability guidance to find it too, without having to jump from one topic to another topic miles away.

To warn you that you are reading a duplicated topic, we included a short note at the beginning of each duplicated topic.

This way if you see a topic twice, you know you are not crazy

You might wonder about the other bundles shipped that don’t appear in the Technical Concepts section (like the Guidance Automation or the Reference Implementation bundles): those bundles that already had a specific section in the existing documentation were kept where they were.

How did We Do It?

To develop our documents, we used an internal tool that converts Word 2007 documents into HxS (Visual Studio Integrated Help) and CHM files. The Southworks team has been part of the dev team of this tool, and I’m happy to see that it has just become a public tool (see the Southworks’s announcement in Spanish). You can get the bits from its Codeplex site: patterns & practices: Documentation Tools.

Feedback Wanted!

Did you find the new docs organization useful? Do you hate it? Do you want to know more about how we design our docs? Please let us know - you can influence on future releases. Feel free to contact team members directly or to post a message in the Codeplex Discussions.