Has anyone considered starting a collaborative, open source JBoss documentation project?
The current JBoss documentation is out of date. Even the “for fee” documentation is lagging behind the current release which is a pretty poor state of affairs anyway, but for a company thats trying to make money out of an open source project it seems pretty foolhardy: surely you need to build as good a level of supporting services as possible? Raw documentation is basically entry level, no hand holding support after all.
Even when it is up to date, the documentation is still not that hot. It could do with a good editor, IMHO.
I’m sure there are a lot of JBoss gurus out there with knowledge to share, so why isn’t this knowledge being gathered together? My impression is that this is actually discouraged, although hopefully I’m wrong. When I first looked at the JBoss project a year or so ago, there were some community docs, but it seemed as if these were being “deprecated” in favour of the for-fee docs. This struck me as odd at the time as basically it amounted to asking users not to write things up and give them away for free. This is counter to my impression of how a good open source project ought to be run, and seems to stifle community building.
Good quality, free documentation would obviously threaten a for-fee product if the latter wasn’t as good. Although I’m pretty sure that throwing a good technical author and/or editor at a set of collaboratively produced documentation ought to yield something even better. The model I’m thinking of is something similar to whats being done with Cocoon: the Wiki is the fermenting ground for the “formal” documentation. Although in that instance, the more structured documentation is free too.
So I’m curious why there isn’t already a community documentation effort, even if it was an unofficial effort separate from JBoss.org? There are great swathes of documentation missing: e.g. architectural design notes, roadmaps, etc. Or if it does exist I’ve not come across it.
Seems like such a beast could be a safety buffer for those of us moving to using JBoss in production, but with uneasy faith in the projects ability to communicate design goals and documentation effectively.
Lost Boy 
I guess we could get a group together to start a wiki to start documenting JBoss..
do know where the free hosting of wikis is?
I agree with you. Many of our developers do not like jBoss because of the awful documentation status. Because jBoss is not a simple system a good documentation would be very helpful for early adopters. Currently I would not recommend everyone to use jBoss not because of quality issues but because of the lack of good up-to-date documentation.
If you start a documentation project I might help you.
The JBoss Group’s entire business model is built around selling documentation and support. Not that they could stop someone from writing documentation, but it doesn’t suprise me that none exists. If you review their business model, I think you might do more harm than good to the future of JBoss. Though, I feel its bound to happen sooner or later.
Dan,
But this is what I find so odd: if their business model is built around selling documentation and support, then why is the documentation so out of date? Why isn’t it more comprehensive?
Perhaps some healthy competition would spur them on? Maybe they could invite people who contribute to an open documentation project to work on the for-fee docs? Perhaps they could charge a small retainer fee for use of the open docs?
There are always business models for a good product.
I don’t think enough open source projects recognise that there are more skills than just coding that could be shared: technical authoring and editing is an obvious one. This should be encouraged.
And I’m certainly not against people making money out of open-source. Quite the opposite in fact. I certainly wouldn’t want the JBoss project to pop its clogs either!
About the lack of good JBoss Documentation
Lost Boy: The JBoss Documentation Project. Why Doesn’t It Exist? And yes – I have been thinking the same for a while. I really wonder if it is such a good idea to have the developers doing the documentation instead…
Browsing the web a few weeks ago, I found http://opensource.objectsbydesign.com/. They have hosted a UML model of the JB3.
I support the effort to set up a wiki-like site for JBoss. There’s too much info out there that is not covered by the docs.
I actually went ahead and bought the documentation for jBoss, thinking that it would probably be a good buy for someone new to jBoss. I started reading it from the beginning, thinking that the author(s) would be clueful enough to study how it is done in the real world, so they would optimise their publication for this mode of consupmtion.
Not so.
The authors display no signs of ever having given even a millisecond of thought to how books are written. Someone needs to get these people an editor so they can drop all the annoying marketspeak (YES WE KNOW jBoss IS A GOOD THING, YOU DON’T HAVE TO SELL IT AGAIN! SHUT THE FUCK UP WITH THE HAPPYTALK ALREADY!), as well as put things that belong in appendices into appendices (no, when setting up jBoss we DO NOT CARE HOW COOL JMX IS BECAUSE WE’RE NOT QUITE THERE YET, OKAY!?).
Anyhow…if you don’t really care about how much the application server costs to actually acquire, you’d be inclined to go for BEA, IBM or Oracle just because their technical writers aren’t completely incompetent.
It would be nice if O’Reilly would put out a book like “Running jBoss” or something along those lines.
I’ve been a supporter of open technologies for quite a time, so JBoss came, to me, as good news in the J2EE front, where, as far as I know, besides JBoss, is completely dominated by proprietary software. I work at Sybase and we too have our app server.
I use to be totally inclined to recommend free, open software to anyone, and one of the reasons is the ease of finding free, excellent quality docs on the Internet. So I decided to try JBoss 3.2.1 with Tomcat, and I can even know what’s the document that is returned when I browse “localhost:8083” (even the port I discovered after some grep work), because the newest docs I have are from 3.0 version. As Mostly Harmless said, market would be prone to think about vendor solutions, because the mantainability of a complex system that is free software with non-reliable documentation could be a shot on the foot.
This year I project to use JBOSS with my pupiles but as I noticed a really documentation’s lack I will never recommand any usage of any free softwar to them and especially I will never recommand JBOSS.
Now there would be a good student project: Writing up a decent JBoss Doc!
This website has got very good JBOSS presentations that I found very helpful..
http://www.madplanet.com/jboss.tea
http://www.madplanet.com/jboss.tea is a good start… hope this will grow as a highly prefered jboss documentation.
JBoss won’t release a good documentation because they are selling technical support… this should be realize by open source community… as this is a bad thing… before we struggle for a philosophy to share the knowledge of the people by opening the source and distributing software for free. Now, its just another chapter. Its basically the same in a different form. Others are opening up everything except for the transfer of knowledge… so that they have the advantage and sell that advantage.