I think Dan has provided a good summary in his introductory article: in short, we would like to respond the challenges that developers face when approaching JBoss technologies by threading paths and handing out maps in the jungle of innovation.
However, I'd like to go a bit Inception on this. A vision of a simple-to-complex set of examples and tutorials that would cover the entire landscape of JBoss technologies, always up-to-date, always evolving, pooling in the collective experience of the JBoss community at large. That's not necessarily a 'why'. More like the 'what' and 'how'.
But. Why ? Here are some thoughts I recently had on this topic:
Because we want to eventually put an end to bad code, ours included. Every time a good example is downloaded, a hundred bugs don't get to see the light of the day. But there's more to that. Often, we'll find even amongst ourselves that we don't see eye to eye on the best thing to do - maybe what we individually think as the best course of action ends in: 'dude, seriously'? I think it's a great opportunity to learn a bit more every day just by taking part in this group's discussions and improve our craft as ambassadors of JBoss technology. Finally, sometimes even the best written example sucks horribly and we all know the way back to the drawing board.
Also, the best code is to be written yet - in middleware and frameworks, but also in the applications that are using them. Writing an example can be a very challenging and creative task, and a venue for discovering the greatest thing since sliced bread. We're all swordsmiths and swordmasters, in varying degrees - and forging the best blade needs the knowledge of both arts.
My last 'why' is because it would be foolish not to. There is a tremendous amount of knowledge pooled between all members of the community - JBossians and non-JBossians alike - and we all know that publish-subscribe can reach more listeners than point-to-point. So, here we are.
Marius, truly inspirational.
What I like, in particular, is that you shine the spotlight on the importance, the value, of the application writer's code base, rather than just ours (the middleware). We tend to think when documenting that we need to explain to readers how the middleware code works, when in fact what matters most to them is how their code is going to work running on our middleware. As you said, they copy a bad example and it sets off a chain reaction of bugs and frustrations.
The better we can frame the middleware in the context of how it can be used, how it should be used, the smoother this engine runs.