Web Client Software Factory Documentation – What is New?

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.