Chris Holmes Online

Nicholas and John commented about something that I think is central to the recent CAB/P&P discussion: documentation. There’s a severe lack of clear documentation when it comes to CAB and I think it is affecting a couple of things. First, I think the lack of documentation creates a barrier to entry; people can’t immediately grasp the power or ease of use of the CAB because there’s nothing that shows it being easy. Second, the lack of documentation causes people to turn to other methods for learning: blogs, reference implementations, inspections. All of which lead the user to think it must be difficult to use. That is part of what creates comments like these courtesy of Ayende:

Nevertheless, “We actually don’t find CAB that hard anymore” – that is after over a year of working with it, right? I would say that it would have to be hard to use after that period of time. Incidently, this is not the only reference for about a year to get the CAB.

And this comment:

About the complexity of the CAB approach, just a few quotes (hopefull not out of context):

* From Sam Gentile: “…I was going to show how to tame this CAB beast…”
* From David Hayden: “I have never had the pleasure of working with the Composite Application Block ( CAB ) or Smart Client Software Factory ( SCSF )”
* From Bil Simser: “I’ve spent the better part of a year learning CAB, EntLib, ObjectBuilder, WorkItems, and all that jargon…”

Complexity is not a good thing, especially when it is exposed to the user.

Here’s the thing: CAB is not hard to use. What it is: flexible, rich, heavyweight. And I do not use that last term negatively.

Sidebar: This post is not about lightweight vs. heavyweight. I know Ayende likes the lightweight approach to his tools. I think that’s a completely valid choice. I also think that a heavyweight framework that attempts to solve a lot of related problems at the same time is just as valid of an approach. In my opinion, which direction you choose is completely personal and should be researched well and fit your business situation. Both approaches work. I think the important thing in both approaches is that regardless of whether you use a lightweight approach or a heavier framework the underlying approach is rooted in solid design; IoC, MVC/MVP, sticking to good design patterns, loose coupling, testability and maintainability. These things must rule, not the specific implementation. End of sidebar.

Let’s address the Year Long Grok.

There are a couple of factors that made grokking CAB difficult. The first thing was that when CAB was released the documentation was thin. I mean razor thin. That’s fine for something simple (meaning: something that solves one problem, not many). You can just sift through a reference implementation or a piece of sample code and get the gist of it. NUnit is like that; just a quick example of a unit test and you know what the thing is capable of. CAB is much more rich and heavyweight than that; it’s a framework designed for solving more than one problem, and when you have something that can solve multiple related problems then a simple reference implementation or a quick look at some code is not going to cut it. You will not gain full, deeper insight with that sort of cursory documentation effort.

I got in on CAB during the final two CTP’s and there wasn’t much there except a reference implementation that showed how you could possibly use it. Notice the use of the word ‘could’. Part of what makes CAB difficult to grok is that it is flexible. There are a lot of ways to solve problems in CAB, and the framework does a pretty nice job of not forcing one particular way of doing things on you. This fact can be witnessed by the sheer number of forums posts during the first two years of CAB’s life where users asked questions like “how do you do X?” and there would be four answers, all different. I find a lot of power in that, but it also creates a lot of responsibility for the developer; you have to know what you’re doing as a designer; you have to build your solution property to fit your needs.

There’s also one other variable to this equation: knowledge. There are a lot of developers working with CAB would aren’t as learned in the concepts of design as folks like Jeremy and Ayende. The lack of design knowledge creates a problem grokking CAB, because they don’t understand the concepts that the CAB is based on. So for them, grokking CAB isn’t just grokking CAB, it’s grokking design patterns, IoC, loose coupling, testability and other key aspects at the same time. It’s like your first time reading Shakespeare as a teenager and having to reach for the dictionary every 5th word. It can be hard to get the meaning of Shakespeare if you’re having to learn the vocabulary at the same time.

CAB is an entry point into the Agile world and into the realm of good design principles, kind of like Shakespeare is an entry point into great literature. Whether folks realize this or not, this is an important fact. So a lot of people are discovering CAB and Agile and design principles all at the same time. A lot of people are being exposed to CAB, and at the same time they’re being exposed to MVC/MVP, IoC, testability, loose coupling and a lot of other good design principles. It can be a lot to grok. And since they are doing it all while learning CAB, it bloats the CAB learning curve. In short, they’re having to reach for the dictionary every 5th word.

So how can something as robust and rich as CAB be exposed as simple and easy to use?

How do you make Shakespeare easy to comprehend?

Cliff Notes. I think good documentation could go a long way toward getting folks to grok CAB in short order. Cliff Notes on CAB. Users have to understand that CAB isn’t hard to use. They have to be able to see CAB’s features in their purest, simplest form so they can see what problems its solving and how it is solving them. They have to be able to see these things isolated and concisely described, with references to the important or relevant background principles if necessary, so they can get a full understanding of what’s going on.

Because if you can’t show a user the advantage of using the CAB – if you can’t show them what problems it is solving and how it is solving them – then the whole point of building it is diminished somewhat.

At any rate, I just wanted to address the whole Year Long CAB Grok. I think there’s a lot more to it than just “CAB is complex”. CAB is built on a lot of principles and patterns, plus it solves more than one problem. Roll that all together and you’ve got a lot to absorb as a developer trying to learn a new tool.