Saturday 27 July 2013

New Railo docs site

G'day:
Bam Bam Bam. Three articles in rapid succession this evening!

I shoulda said something about this earlier, but it slipped my mind. Mark Drew has been beavering away getting the new Railo online docs sorted out, and they're now live.

The site is here: Railo Documentation Viewer.

Wanna know the best thing? This is the URL for the docs on <cfassociate>: http://railodocs.org/cfassociate. I did not look that up, I just knew all I needed to do is to type the tag (or function) after the domain name, and it works. Contrast this with Adobe's equivalent docs. Take a deep breath... http://help.adobe.com/en_US/ColdFusion/10.0/CFMLRef/WSc3ff6d0ea77859461172e0811cbec22c24-7f5b.html. Got that? Railo seem to have a better grasp of web concepts like SEO and URL hackability than Adobe have (well if Adobe does, they don't care).

On SEO... if I search for "railo docs cfassociate" the first link is the page above. If I try "coldfusion docs cfassociate" I get the CF8 version of the docs as the first link, and the docs for ColdFusion 7 are third. ColdFusion 9 and 10 don't actually show up on that search, but Google displays them as results for "similar" searches: "coldfusion docs cfassociate", then the CF9 docs are listed. Oddly, if I actually do a search for "coldfusion cfassociate", I get the CF8 match first, the CFMX7 match on the second page (who the hell every looks at the second page of Google's search results? ;-), and by the time I gave up... page 5... I'd still not seen a link to the docs for any currently-supported version of ColdFusion. Blimey on page 3 there was a link to this blog of me talking about the tag, but nothing from Adobe on CF10 or even CF9. Slack. How can a web company be so poor at making sure their own docs are googlable?

Back to Railo... the next good thing is that the tag & script docs are on the same page. Unlike on the Adobe docs where the script docs are buried as an afterthought elsewhere, with not a cross-reference to be seen. Cool!

And they promote community participation right there on each page with a big, Disqus-based commenting option. I know the Adobe docs also has commenting, but it's very downplayed, and not even visible if one has a Flashblocker installed (and doesn't everyone?)

I also presume - given Railo is open source - there's a way for me to edit these docs too. I have to say I cannae spot how to do so on the page. I'll find out how and report back.

This is great work from Mark and Railo in general.

Nice one.

I hasten to add that Rakshith has been promising an open-source / editable / community-driven facelift for the ColdFusion docs... well it was mentioned a few months ago, but I've not heard anything since. But anyway maybe Adobe have realised how far they need to pull their socks up, and an equivalent for ColdFusion will present itself soon..?

--
Adam