I've been on the prowl for Flex frameworks and libraries we can use here to help us both organize and speed up our multimedia development. I keep running into the same problem over and over again, though: people who write frameworks and libraries don't know how to describe their tools.
Here, for example, is the first paragraph from the first page of the Cairngorm project, Adobe's favorite framework for Flex:
Cairngorm is the lightweight micro-architecture for Rich Internet Applications built in Flex or AIR. A collaboration of recognized design patterns, Cairngorm exemplifies and encourages best-practices for RIA development advocated by Adobe Consulting, encourages best-practice leverage of the underlying Flex framework, while making it easier for medium to large teams of software engineers deliver medium to large scale, mission-critical Rich Internet Applications. [ Cairngorm ]
Oh. Alright, then.
Here's competing framework PureMVC:
PureMVC is a lightweight framework for creating applications based upon the classic Model, View and Controller concept.
Based upon proven design patterns, this free, open source framework which was originally implemented in the ActionScript 3 language for use with Adobe Flex, Flash and AIR, has now been ported to nearly all major development platforms. [ About PureMVC ]
The problem here is that both Cairngorm and PureMVC are rushing towards explaining development philosophy or implementation details. They don't describe what problem they're trying to solve.
The jQuery web site does a much better job:
What am I supposed to do with "exemplifies and encourages best-practices for RIA development advocated by Adobe Consulting?"
If you are writing a framework or library, remember that people will want to use it because of the problems those tools solve, not because you have a good design philosophy or cunning implementation. That's important, too, of course.
But first tell me what the thing does and why I care.