The quality of the new ColdFusion docs in one quick screencap

G'day:

This is from Creating and Using Custom CFML Tags.

Chuckle.

--
Adam

CFML: nice work Pete (cfdocs.org)

G'day:
What a productive lunchtime I've had today. Well: blog-wise.

This is timely. Adobe have messed the ColdFusion community around yet again by moving the docs site to a read-only affair, and one that gives a security warning whenever one clicks through from Google.

Pete Freitag has stepped up and is more actively trying to engage the community in helping maintain cfdocs.org: he's gamified it! He's added a leaderboard to the home page:

And also good on that rogue's gallery for helping out & giving back to the community.

I think perhaps it might be an idea for the ColdFusion community to vote with its feet and use cfdocs.org as our home base for CFML doc references.

Right. Back to work for me.

--
Adam

ColdFusion docs site: update and question

G'day:
I've received official word from Adobe as to the fate of the ColdFusion wiki (see yesterday's article "Is the ColdFusion community about to lose the ability to update the docs?"). What do you make of this?

Dear Adam,

Two years ago, we together made a decision to move ColdFusion documentation to a wiki model so that we can open the documentation up to chosen ColdFusion experts to improve and add value to the content. Today, we are at a juncture, where in, we have to move away from the wiki model temporarily due to multiple issues. From starting next Monday, 28 Sep 2015, ColdFusion documentation will go live at helpx.adobe.com. We will share with you the link to ColdFusion documentation when it goes live.

Meanwhile, we would like to not miss out on the value add you have been doing to ColdFusion documentation. Hence, we are setting up a DL (DL-CHL-CF) to which we will be happy to receive any information you deem right to be included in the ColdFusion documentation.

Thank you for supporting us,
ColdFusion documentation team.

So there we go. That sux. I am interested to know why they're moving away from the wiki model temporarily. And what sort of units of time this temporary state of affairs ought be be measured in.

More importantly, can anyone explain to me what the hell this means: "we are setting up a DL (DL-CHL-CF)". What the hell does that sequence of words mean? And is it reasonable to think I might already know what a DL is (especially a DL-CHL-CF one, as opposed to some other sort of one)?

I think the ColdFusion community is about to lose a great resource.

And I'll let you know when I find out what at DL is. A -CHL-CF one, at that.

Update:

Here goes, I got a reply from Adobe on this:

DL is a mail distribution list. It’s a mailing alias (we will communicate to you as soon as it is set up) in which the CF documentation team members will be available,

I'm not sure how anyone expected anyone to infer "DL" meant "a mailing list", but then again Adobe aren't exactly known for clarity or thoughtfulness of communications.

I have, btw, opted out of participation in their mailing list.

Righto.

--
AC

Is the ColdFusion community about to lose the ability to update the docs?

G'day:
(Hopefully this is a nod to Ian Betteridge in my subject line there).

I read this last night, on ticket 4010693:

Update: Adobe has copied the wiki docs over to AEM (Adobe Experience Manager). The AEM docs cannot be edited by anyone outside of Adobe. The wiki will be taken offline in about a week or so (guessing October 1st).

To verify, see Adobe's comments here: https://bugbase.adobe.com/index.cfm?event=bug&id=3921578

Thanks!,
-Aaron

And the comment in question is (from the pleasingly named "Jacob Jayakar Royal"):

Yes, Nitin, already migrated. All our CF content is there in helpx already. Wiki pages can't be viewed after a week or so.

So... um... what?

The only useful thing Adobe have ever done with the ColdFusion docs is to put them on the wiki so we (ie: the community) could actually fix them up. And now it seems they're taking it back in house?

I can't see anything that confirms Aaron's comment that "The AEM docs cannot be edited by anyone outside of Adobe", but that would really suck if it was so.

It would be really good if someone from Adobe (I'm looking at you, Anit) could clarify what's going on here?

Cheers.

--
Adam

CFScript docs now on GitHub

G'day:
That CFScript documentation thing I released the other day ("Documentation for CFScript") is now on Github @ "CFScript documentation".

Currently it's a duplicate of the stuff on the blog article, but the GitHub one will be treated as the master copy from now on. I am in the process of simply embedding that back into the original article so that the article is always current. I should have that done in the next day or so.

Underlying Java methods of CFML objects

G'day:
A week or so ago, I wrote an article 'Using "undocumented" methods'. This got mention on CFHour last week: "Show #206 - Mucho Happy Box", and one observation I think Scott made was that it'd be useful to know what methods were available, even if one might not necessarily want to use 'em (see the earlier article and its comments as to why one might not want to use 'em).

Anyway, ages ago I came across a handy Java class, ClassViewer, which enables one to inspect the underlying methods of CFML objects using Java reflection. I wrote an article about it "ClassViewer.java", and posted the source code. I hasten to add it is not my own work, but it is jolly handy code. I also knocked together a CFML version of it: "ClassViewer.cfc" (Gist). I've gone through a pumped a bunch of CFML objects through this, and saved the output on my CFMLDeveloper account. Here's links to 'em all:

Adobe ColdFusion 10 docs now-community maintainable

G'day:
This is good news. I have just been able to "fix" an entry in the Adobe ColdFusion 10 docs!

Documentation for older versions of ColdFusion

G'day:
Gavin was asking about docs for older versions of ColdFusion today. In my searchings, I've located the docs for a number of older versions of ColdFusion. I'm gonna list 'em here so they're easier to find.

• Cold Fusion 2.0 online documentation, courtesy of GES technologies (update 2015-05-07: link is now dead)
• Cold Fusion 3 online documentation, courtesy of House of Fusion (update 2016-06-30: link is now dead)
• ColdFusion 4.5 online documentation, also courtesy of House of Fusion (update 2016-06-30: link is now dead)
• ColdFusion 4.5.2 offline downloadable documentation, courtesy of Adobe (these are zip files)
• ColdFusion 5.0 offline downloadable documentation (Adobe, zip files)
• CFMX 6.1 offline downloadable documentation (Adobe, zip files)
• CFMX 7 offline downloadable documentation (Adobe, zips)
• ColdFusion 8 online documentation (Adobe livedocs)
• ColdFusion 9 online documentation (help.adobe.com)
• ColdFusion 10 online documentation (the current rendition of Adobe online docs: learn.adobe.com. I wish they'd just stick with the same bloody domain name / online docs structure!!). That site is now dead. But the docs are here: ColdFusion Documentation Archive.
• ColdFusion 11: same page as above, but that's a direct link.

Hopefully that's helpful to someone.

Righto...

--
Adam

ColdFusion 10 docs are under Creative Commons licensing

G'day:
This is just a follow-up to my weekend's article regarding the "archiving" of ColdFusion documentation. At the time I had a query regarding who the CF10 docs are licensed. The CF9 ones are cleared labelled as being under a Creative Commons licence (bottom left of each page), as per this example from the <cfabort> docs page:

Today Frank Jennings from Adobe contacted me, with the following information:

On Twitter:

@dacCfml @cfjedimaster @RussMichaels @Adobe CF10 docs are covered under CC that allows anyone to share with attribution & without resale.
— Frank Jennings (@fermatjen) September 16, 2013

Scraps, scrapes and soup

G'day:
Yesterday I noted - fairly "emphatically" - that changes to Adobe's ColdFusion docs site (not the new flash-harry CF10 stuff, the old stuff that they never update) have allegedly broken some community sites like cfquickdocs and CFGloss (the latter is currently redirected to the site's homepage). This seemed to be because the HTML structure (or the URLs? I don't actually know for sure) had changed and these sites relied on scraping the site to get the content for their revised UI for the CF docs. These sites exist because the CF docs site is not particularly user friendly as far as searching and navigation goes. And the URLs are completely unhackable (in that good sense of hackability, eg: "cfabort.html" would be good because one could infer other tags' pages from it; "WSc3ff6d0ea77859461172e0811cbec22c24-7fde.html" is bloody stupid), so whilst the content is OK, finding it can be a challenge sometimes.

Stop Press:

CFQuickDocs is at least partially back up again. The CF8 and CFMX7 docs work: CF9 still doesn't.

Ray pointed out that it's entirely Adobe's prerogative to change their URLs/HTML if they want, and went on to say anyone relying on page scraping for their content need to be aware of the instability of their chosen approach. And, accordingly, if Adobe changed their docs, it's not their fault if other sites break. I would say that given they performed the action that caused the breakage that it is their fault. However - all things being equal - it's perhaps not something they should intrinsically lose sleep over. That's the thing, though: I don't think all things are equal here. These third-party documentation sites are providing a service to the community that works around shortcomings in Adobe's own approach, and accordingly I think they warrant some respect from Adobe. My own case in point is that I need to scrape bug content from the bugbase for my CFBugNotifier process, because there's no other way to get the info. And given Adobe don't see fit to provide notifications when bug status changes, I think I offer a community-useful service here. And if they changed the bugbase mark-up and CFBugNotifier broke, that would be a detriment to their community. And their fault

Another consideration is that the Adobe docs - except the CF9 ones (and formerly the CF10 ones, I found out today: "ColdFusion copyright and trademarks and third-party notices") - are copyrighted. So people aren't really supposed to be copying them for their own use. Which is what page-scraping is doing. This is why my "copy" of the bug-base entries doesn't maintain the actual content, it maintains a hash of the content. That way I can quickly check if anything has changed (if not exactly what has changed). This doesn't infringe Adobe's copyright.

Anyway, whatever. I think I was a little more belligerent about it than I needed to be, but I think also that Ray was a little more dismissive of the broader picture than he needed to be (whilst being technically correct). And this blog article is not about that anyhow (he says, being almost 500 words into it!).

Preventing Adobe from messing with ColdFusion community projects

G'day:
I was chatting to me mate Andrew Myers on Twitter this morning, and he brought this Twitter exchange about - basically - the death of CFQuickDocs at Adobe's hands to my attention:

Railo docs licence weirdness?

G'day:
I just noticed this in the licence (yes, I read licences) for the new Railo docs site:

The Railo Docs Site by Mark Drew (@markdrew) is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License.

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?

Improving CFML's documentation

G'day
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.

Arrays in CFML (part 3)

G'day:
This article finishes up the coverage of array functions in CFML (there's more to discuss than just the functions: I'll get to that stuff in yet another article). Most of the array functions were covered in an earlier article, and I'm just finishing of the rest of them here. The functions here haven't been put in a separate article for a good reason: it's just that I'm daft and forgot to put then in the earlier article that should have included them. I dunno how I missed them of the list initially, as I based my "todo list" on the list of functions on the "Array Functions" page from the CF docs. Like I said: I'm just daft. Anyway... here they are.

Quality of CFML documentation

[This is a "toned-down" edit of the first draft I made of this doc.  The initial doc had a bit more vitriol in it than would be considered helpful.  Plus I was going to have to give it an NC-17 rating for its language.  It's a good thing to draft something then cool-off before pressing "send" sometimes]

G'day:

I've had a long day, some things that could gave gone smoothly didn't, and I'm in an intolerant mood. Some would say "sounds pretty much like your default setting, Cameron". Fair cop.

Anyway, I'm trying to write this second article about ColdFusion arrays (now complete... I started on this rant a few days ago), and I'm reading the official Adobe docs for inspiration (OK, not "inspiration", I guess. Anyway: I'm reading their docs).

Arrays in CFML (part 2)

G'day:
In this article, which is part two in an ongoing series, I'll discuss the various functions CFML ships with for working with arrays. The first part described what an array is, and how to create them.

The online docs cover each of these functions too, but the coverage is pretty superficial. They cover all the syntax options and give a code example, but they don't go beyond that. Having been around the block a few times (and thus... err... ending up back where I started.. hmmmmm...), I've picked up the odd but of insight, and have explored some of the idiosyncrasies of CFML that isn't covered in the docs. I shall try to discuss why one might want to use a given function, rather than just cataloguing that it exists (which is all the official docs seem to set out to do, at times).

The docs are good for something though: they do act as a good lookup of what's available, so go have a look at then after yer done here.

Anyway, enough waffle...