On Fri, Jul 9, 2010 at 2:01 AM, Adam Cameron <[email protected]> wrote:
> My dig regarding lack of CFML docs was more aimed at the historical > situation with New Atlanta relying on Adobe to provide docs for them, > which I think was a bit "commercially exploitative" of them. I > understand you're an open source project so rely on the help of others > to get stuff like docs done. Fair enough. > Just to add to Alan's excellent response, this seems rather an odd charge to make. Apache, JBoss, IBM, Oracle, and the rest don't each independently produce Java documentation for their servlet containers or JEE engines, but rather only document any differences or enhancements they each have when compared to the Java specs. The difference in the CFML world is that until the alternative engines came along, there was no real separation between ColdFusion the product and CFML the language; in other words, Adobe was the de facto CFML spec since none existed otherwise. Given this, it seems completely natural to me that the other engines (Railo would fall into this camp as well) would document differences and enhancements as opposed to writing ground-up documentation. I don't see that as commercially exploitative any more than IBM not writing Java language documentation to go along with Websphere would be commercially exploitative of Sun's documentation of the Java language. That being said, as we've moved forward on OpenBD it makes more and more sense for us to generate our own documentation for numerous reasons, and the addition of documenting straight from the engine is a huge step forward on ensuring that the docs are always up to date. The CFML manual is already a fantastic resource for all CFML developers, and will only continue to grow. > > I talked to Gert & someone else from the Railo team about trying to > get Adobe, Railo, New Atlanta and I guess someone from the OBD team > together round a table and agree on a common, unified (and "open > source" / wiki-ed) documentation repository for all of the competing > CF engines, as a gesture towards strengthening the CFML community. > This was at a time when Railo seemed to be wanting to get their own > open-source docs off the ground, but were getting very little > community buy-in. > This is what was starting to be tried with the CFML Advisory Committee, but unfortunately that effort didn't get very far for a host of reasons. And it's interesting Railo didn't get much community buy in on their open source docs effort; frankly I suspect it's because not many people saw it as necessary enough to burn the time it would take to do this well. As Alan said, our docs are Creative Commons and could serve as the basis for this type of effort if someone wants to take it on. The people involved with the OpenBD project will naturally spend our time focusing on OpenBD, but by releasing the documentation under a Creative Commons license we're making our efforts available so they can benefit the CFML community at large. > However nothing came of this, and I have to concede I never chased it > up. > As you probably discovered that's a very tough nut to crack. After being involved with the CFML Advisory Committee and seeing how that went, in my opinion this isn't a very fruitful path to try and follow. > I'm all for community participation, but I think it's a waste of > resources for each CFML flavour to have its own duplicate of the CFML > reference This is an interesting comment given the "commercially exploitative" dig above. It seems as though you're simultaneously saying that the other engines both should and should not reinvent the wheel as far as documentation is concerned. Again to echo what Alan said, we are where we are at this juncture, and I think we've made massive strides in recent months to ensure that OpenBD has its own set of documentation that will always be current. Clearly there's more work to do, but we're getting there. > It'd be more helpful > for the community as a whole to have one centralised (and flavour- > neutral!) version of this. > Again, this is what the CFML Advisory Committee was attempting. Honestly the only way an effort like this will succeed in my opinion is if someone from the community at large picks up this ball and runs with it. Personally I'm not convinced having a vendor-neutral centralized documentation source is necessary because, as you said, 99% of the documentation would be more or less the same, and people can get that from Adobe, OpenBD, Railo, or numerous other sources. It's more important to me personally that I spend my time contributing to the OpenBD documentation since that's the project with which I'm involved, but these efforts will absolutely benefit the CFML community at large if they choose to take advantage of the great stuff we're putting out there. > > For my part, I am and will remain primarily a CF user, and am only > really using OBD because of the remit of this current project, so I > don't have the... err... "OBD community spirit" (or whatever) to want > to invest my time writing docs for it. I'm happy to raise & discuss > bugs I find though. Esp if you continue to fix 'em so quickly! > Thanks for the bug reports Adam! Even if you don't have the "community spirit" as you put it, submitting bug reports as you're doing is *tremendously* helpful to the project, so we greatly appreciate it. And who knows, maybe now that you see how quickly things get fixed on an open source project you might just catch a little OpenBD fever. ;-) Really appreciate all of your input and feedback. -- Matthew Woodward [email protected] http://blog.mattwoodward.com identi.ca / Twitter: @mpwoodward Please do not send me proprietary file formats such as Word, PowerPoint, etc. as attachments. http://www.gnu.org/philosophy/no-word-attachments.html -- Open BlueDragon Public Mailing List http://www.openbluedragon.org/ http://twitter.com/OpenBlueDragon online manual: http://www.openbluedragon.org/manual/ mailing list - http://groups.google.com/group/openbd?hl=en
