I started rambling on in response to a thread on the Railo newsgroup, but after I'd typed about 500 words I thought it was getting a bit long for a forum response, plus it's relevant to more than just Railo anyhow, so I'd centralise it here, and put a summary on the forum and a link back to here.
The gist of the bit of the discussion I was interested in is this bit:
Alan Holden said:
On the documentation front... and this transcends Railo a bit:
I wish there was a "CFML Rosetta Stone". It would be something like CFDocs, but with a matrix architecture so you could quickly x-reference a tag or function across ACF, Railo and OpenBD (& even desktop, cloud, Jakarta, Tomcat versions, etc). This would help us develop apps that worked across the spectrum, help us solve those "it worked here, why not here?" bugs, and thereby help to advance CFML in general - to the benefit of all.
Unfortunately, this will probably remain a wish for some time... for it would probably need to be housed and managed separately, and would take a little chunk of time (and money) to develop and maintain.
And Mark Drew replied:
Why don't you get it started?(I hope you don't mind me quoting you, guys: I figure the forum is pretty much "public domain").
They're both good points: identifying the need, and a suggestion to do something about it.
I had a look at the logistics of doing this a while back, for a coupla reasons:
- I think the volume of docs that Adobe provide for CF are good, and the coverage is very bloody good, but the quality is lacking: the narrative is superficial and explains what some functionality does, but not why one might want to do it, and nor does it cover and sensible use cases or document ant gotchas.
- Obviously it only covers CF (not Railo or OpenBD's idiosyncrasies, or purposeful divergence from ColdFusion's implementation of CFML).
- Its approach across versions is poor: it has different copies of the docs for each version. What sux about this is if I put an annotation against the docs for - say - CFMX7, it's not there in the subsequent CF8 (and onwards) docs, even though it's quite likely still relevant. This kinda makes me feel any participation I do engage in to improve the docs is wasted effort once the next version comes out.
- The thing is rife with bugs and errors, none of which I can fix. I can raise them with Adobe, but whether they do anything about when is hit or miss. They're actually been pretty good about this recently though.
I looked at starting a DIY project, and how I would approach it. This was a coupla years back now, and one of the first things that seeded in my head the notion to do a blog.
One of the things I wanted to make sure is that it was a collaborative thing: I know I start a bunch of stuff and never finish it, and I don't see why that project would be any different. Also because whilst it's an admirable undertaken, and even though I like doing documentation (weird, I know), it does get tedious after a while. Plus it's just a shitload of work for one person to do. It also needs to be collaborative because otherwise we'd just get one other person's take on how docs should be done (ie: first there was Adobe's, then there'd be mine) and we'd be no better off.
So I started looking at what it would take to set up a MediaWiki site, and whether MediaWiki could do the trick.
The hosting of it is easy: Wikia will handle that.
Mediawiki articles (like Wikipedia, etc), tend to be more free-flow than one would want for language documentation: one would want a moderately uniform set of sections per page, so that users find it easy to use. I did some superficial hunting around the MediaWiki docs, and it seems there's no problems with that: there's a whole section in the docs on skinning the things, which from superficial reading seemed to do the trick (I didn't re-read it just now, this is just my recollection from the last time I looked at this).
One challenge with the skinning is that it's all done in PHP. And whilst I can sort of read PHP and do "Hello World", I do feel a bit dirty using it (not for any CFML vs PHP thing, just because it's a pretty shonky language), and am not sure if I want to get up to speed with it just to be able to skin wiki pages to my liking. This is a small barrier though.
The next hurdle... or what I thought was a hurdle... was content. As I said, the content of the Adobe docs is 80% there, and as I'm no believer in reinventing the wheel, I thought it would be good if I could be allowed to use the Adobe docs as a starting point... that would get a lot of content in straight away. I didn't think I'd be able to get permission to use their content, and beyond mentioning it to someone there in passing (and this was never followed up - my fault as I never made it a proper inquiry), that notion died and my attention moved on to the next shiny pretty pretty thing.
However this has just resolved itself. By my reading of the legalese on the Adobe help site - starting here, and ending up here, and here... it's already free to use anyhow, being licensed under the creative commons licence anyhow. The bottom line from the third link is this:
You are free:So that's cool. That would make a good baseline for making a publicly collaborative CFML docs project.
- to Share — to copy, distribute and transmit the work
- to Remix — to adapt the work
So I think I'll float this idea back to the Railo newsgroup, the OpenBD newsgroup, and... err... there's no point in posting on the Adobe CF forums because they don't pay attention to that. Um... well I'll mention it to Ray Camden too. He pays attention.
I don't want to just dive straight in to an undertaking like this, but I'll at least try to get some sort of discussion going.
(I also have this crazy idea about porting MediaWiki to CFML now...)
But first things first: I'm off work for the next week, and I feel a mission to the forest beckoning.
Righto.
--
Adam
