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).
Here's the example code block for arrayAvg():
<!--- This example shows the use of ArrayAvg. --->
<!-- The following lines of code keep track of the form fields that can
be dynamically generated on the screen. It uses the Fieldnames variable
with the ListLen function to determine the number of fields on the form. --->
<cfset FormElem = 2>
<cfif Isdefined("Form.Submit")>
<cfif Form.Submit is "More">
<cfset FormElem = ListLen(Form.Fieldnames)>
</cfif>
</cfif>
<html>
<head>
<title>ArrayAvg Example</title>
</head>
<body>
<h3>ArrayAvg Example</h3>
<p> This example uses ArrayAvg to find the average of the numbers that you enter
into an array.<br>
To enter more than two numbers click the <b>more</b> button.
</p>
<form action = "arrayavg.cfm">
<!--- The following code initially creates two fields. It adds fields if the
user presses MORE. FormElem is initialized to two at the beginning of this
code to show that the form has two fields. ----->
<input type = "submit" name = "submit" value = "more">
<table cellspacing = "2" cellpadding = "2" border = "0">
<cfloop index = "LoopItem" from = "1" to = "#FormElem#">
<tr>
<cfoutput>
<th align = "left">Number #LoopItem#</th>
<td><input type = "text" name = "number#LoopItem#"></td>
</cfoutput>
</tr>
</cfloop>
</table>
<input type = "submit" name = "submit" value = "get the average">
</form>
<!--- Create an array. --->
<cfif IsDefined("FORM.submit")>
<cfset myNumberArray = ArrayNew(1)>
<cfset Count = 1>
<cfloop index = "ListItem" list = "#Form.Fieldnames#">
<cfif Left(ListItem,3) is "Num">
<cfset myNumberArray[Count] = Val("number#Count#")>
<cfset count = IncrementValue(Count)>
</cfif>
</cfloop>
<cfif Form.Submit is "get the average">
<!--- use ArrayAvg to get the average of the two numbers --->
<p>The average of the numbers that you entered is
<cfoutput>#ArrayAvg(myNumberArray)#.</cfoutput>
<cfelse>
<cfoutput>Try again. You must enter at least two numeric values.
</cfoutput>
</cfif>
</cfif>
</body>
</html>
For goodness sake! There's a form, there's HTML, there's sixty-one lines of code, and only one of them is actually related to the function being demonstrated! Not to put too fine a point on it, but who writes this sh^h^hstuff?
Here's a lucid example of arrayAvg():
<cfset myArray = [1,2,3,4,5]>
<cfdump var="#myArray#">
arrayAvg: <cfoutput>#arrayAvg(a)#</cfoutput>
There. Clear, concise, unambiguous, and something anyone can relate to. Without the code being 95% pointless baggage (I could ditch the <cfdump>, too, really).
I realise arrayAvg() is not the most important function in the CFML corpus, but I didn't single it out, it just happened to be the doc page I was looking at when my derision overran. I saw other pages demonstrating other array functionality that had database queries in them! I've actually seen doc pages in which the sample code doesn't actually even use the function being documented. I'm not kidding (I wish I could find the example). This is pretty much representative of the impenetrable nonsense that makes up the CFML guide.
I was recently berated by someone at Adobe (aah... I wasn't going to mention your name, Ray, but I need to cross-reference to the very conversation we had, so... err... it was you mate. Sorry. I'm sure you stand by what you said though, so hopefully I'm not singling you out or dropping you in it) when I last observed that the quality of the docs was pretty ordinary. They said something to the effect of "there's 5000 pages of free documentation!". No. My employer has sunk hundreds of thousands of quid into CF. My previous employer only tens of thousands. The one before that over a hundred grand. This is not counting the clients of the agencies I used to work for (I'm inhouse at my current employer; the rest have been agencies). And when buying an enterprise licence, we're paying for the whole package, not just the software.
The quality of the docs should reflect the investment Adobe expects us to make in their solution. Not simply 5000 pages of poorly maintained, incoherent content which seems to be worth precisely what Ray indicated they cost to me.
To be fair, some of the stuff in the Developers Guide is OK. For example I have the regex docs page bookmarked and refer back to it on a regular basis and refer my coworkers to it when they need help with regex guidance. The examples aren't as in-depth as they could be, but the syntax is represented in totality, and clearly (and on one page, which is handy).
But - on the whole - I too-often find myself looking up the docs, reading a page, and finding myself none-the-wiser for it. And it's not like I'm completely stupid (well I like to tell myself this...).
The most important part of the docs is the CFML Reference, and this needs a significant revamp. One of the things I'd like to see in CF11 is an undertaking to bin all of it, and start again. Rewrite it from the ground up, and create a single resource for anyone needing to start with no knowledge of some piece of functionality, and explain to them how it works (syntax definition), and code examples of all its vagaries and options, as well as "expert" content as to why one might use the functionality. And explain its idiosyncrasies and stuff that might not be immediately apparent. It should also be implemented in a wiki-style approach, so the community are encouraged to add to it and keep it up to date/correct. Currently we can add comments, but we cannot correct obviously wrong content.
Also all the various versions should be rolled into one source, with the current version being the focus, and annotations where previous versions differ. We don't need a different set of docs for each different release of the language. For one thing, the comments are never migrated between versions, and most comments I've added over the years still apply to the language today, as much as they did in CFMX7 when I first mentioned it. That's effort I've undertaken to help basically wiped-out by Adobe. Not great.
That said, if Adobe undertake to do this, I volunteer to help.
Now... back to why I decided to drop Ray in it (err... I mean "cite a comment Ray made" ;-)... when trying to find his quote, I found the original blog articles I was commenting against. It's this one entitled Initiative to improve ColdFusion docs. So here's my question. What happened to this, Ray? I've heard nothing about it other than your original blog post. I'll add a follow-up comment to that blog entry too, in case you're not a habitual reader of my prattlings.
Anyway, I've got a hard slog at work today before I can escape to the Emerald Isles, and I better crack on with it...
Righto.
--
Adam
