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!

In a previous post I commented about the book The 7 Habits of Highly Effective People, which we use as part of our mentoring process. In this case Diego Marcet, a new southy that joined the company a week ago, wrote a blog entry giving his impressions about this mentoring process. He says:

[...]

The first thing that caught my attention these first days is how much importance the company gives to communicate its philosophy of work. In all my previous jobs I always had a day or two for reading a couple of documents about the company and the project I would be working on, and immediately after that I’d start coding. Here it’s the opposite thing, first you have to focus on understanding the philosophy the company has and how they expect you to behave (like being proactive, collaborative with teammates, and so on)

[...]

I’m happy to see he understands this at his fourth day at the company because our culture is, in my opinion, what helped us be where we are and what will help us reach the next level as a company. Good start!

But don’t be scared - there is technology during the mentoring process too (we are a technology company!). As Diego says, one of the first things you learn is Test Driven Development and Scrum. But what I want to highlight here is that first we try to prepare our southies in a environment where they can safely fail and learn our culture, so that when it’s their time to tackle real-world business challenges, they are better prepared.

Want to learn more about our culture? See the Mindsets and Core Values.

Want to see how we work at Prism? Don’t miss this great post from Glenn. He describes the team, how we work, what being at the team room feels, and he also shows pictures of the (distributed) team and includes videos that show how we do iteration planning.

The Prism team.
1st picture: Redmond, WA, USA. 2nd picture: Buenos Aires, Argentina. 3rd picture: India

This is a question I made myself many times:

What book would you recommend to a guy that is new to your company?

or even this one:

What book would you recommend to a guy that is new to your company, who has never programmed Object-Oriented and who has never worked with .NET or Java?

Typical answers would be something like Thinking in Java or Introducing Microsoft .NET. And yes, these books would probably be included in my answer. But at Southworks our culture does not stop at technology. Technology is a key part in the company’s culture, but technology on its own is not enough. At Southworks, our core is the people.

Damian is a young guy that has just joined the company. In fact, he is the youngest member of the company; when he entered he was only 17 years old. As part of his initial training, we asked him to read the book The 7 Habits of Highly Effective People (together with other technical books).

Why this book? Because at Southworks we pursue most of the things this book promotes. This book is not about technology at all - it is about personal and professional development, and it is in line with Southworks’ culture.

Damian has just finished reading the book and did a great post about it. In the last paragraph, he says:

In an utopic society values would be the center stone, and most habits in this book would be followed by all, but it is not the case.

I couldn’t agree more. However, Damian, do not be frustrated - at least at Southworks you will find people that place values and these habits in the core of their life. And that, I believe, makes Southworks a special company and a great place to work at.

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.

In case you missed it, Mariano Converti has been blogging about the Composite UI Application Block and Smart Client Software Factory in spanish. It's good to hear that because there are very few people blogging in spanish about CAB and a lot of hispanic CAB users, so this is very valuable to the community.

Here is the list of posts that he has published so far (more to come for sure!):

• Introducción a Composite UI Application Block (CAB) I (Intro to CAB)
• Introducción a Composite UI Application Block (CAB) II (Intro to CAB applications initialization) 
• Introducción a Composite UI Application Block (CAB) III - (Intro to Modules)
• Introducción a Composite UI Application Block (CAB) IV - (Intro to MVP pattern)
• Introducción a Composite UI Application Block (CAB) V - UI Extension Sites (Intro to UI Extension sites)

Johnny reminded me with this nice post that one year ago, we were working together in Redmond for the Web Client Software Factory project; I can’t believe how fast the time goes, thanks Johnny for the remainder!

Looking at the collage he assembled a funny unit test came to my mind. Yes, a unit test that appeared in the team room on my 21st birthday:

Isn’t it a nice way to say "happy birthday" to a geek? (Pocho’s my nickname…)

And, of course, this picture that I won’t forget:

Matias Woloski, Bill Gates, Eric Rudder (in the back) and me.

Unfortunately, due to the fact that I’m still in college I couldn’t travel again (actually I traveled on March for the WC-SF workshop, but it was just a one-week trip). However, other southies of my team had the chance to travel: Julian, Miguel and Juan, which makes me happy. And even though I cannot travel so often, I’m glad because I have been working since then with the amazing p&p team (from Southworks offices at Buenos Aires, Argentina), on the SC-SF v2 and WC-SF v2 projects. Thanks to p&p and Southworks for these great experiences!

More pictures from the trip:

• Strategic Architect Forum @ redmond - Picture with Bill Gates
• @ Redmond
• Some pictures from the Web Client Software Factory team

We released a draft version of the hands on labs for Smart Client Software Factory almost a month ago, and we got over 1000 downloads. We will release the final version soon which will include, apart from the current labs, the following ones:

• Adding offline capabilities to your solution through the Disconnected Service Agent Application Block
• Using WPF views

This is a great opportunity for you to influence on the final version of the labs. Please let us know what you think about the draft release, by either leaving your comments in our blogs, contacting us directly or posting in our community site. The following questions might help you:

• Suppose you are starting a project that uses SC-SF. Would you recommend your team members to read the labs?
• Were the procedures clear enough?
• Did you find the background information and content useful?
• What topics need further explanation?

Thanks in advance; your feedback will help us improve the labs.

After a long waiting, the hands on labs for WC-SF June 2007 are out

Download

The labs are based on the ones we used for the workshop held in Redmond on March 2007, but they contain a lot more content, background information, and revised procedures. Please let us know what you think about them.

Content

1. Lab 1: Creating and Initial Web Client Solution with a Business Module
2. Lab 2: Creating a Service
3. Lab 3: Adding Views and Unit Testing
4. Lab 4: Databinding with the View-Presenter pattern
5. Lab 5: Creating a Foundational Module
6. Lab 6: Authorization
7. Lab 7: Logging and Exception Handling
8. Lab 8: Using Page Flow