Posted in ColdFusion | Posted on 06-28-2011 | 3,562 views
Even though I'm a contributing author to a set of ColdFusion books, whenever I can I try to sing the praises of the 100% free 5,000+ page set of docs Adobe created for ColdFusion. I hear people complain about bugs and bad examples, but you can find mistakes in the WACKs as well. (Of course we try for perfection, and we are just as successful as everyone else.) That being said, today Adobe announced (in a private list) an initiative to help improve ColdFusion documentation. This initiative is being driven by Adobe with members of the ColdFusion community and is based strongly on comments you guys leave on the online versions available at help.adobe.com. If you've found issues with the docs before, now is the time to leave your comments. As always, try to be as descriptive as possible. Saying "It doesn't work" is pretty useless. Describe what part of the documentation isn't working for you and how it isn't working. Saying "I don't get it" also isn't typically helpful. Try to explain what part of the documentation you're looking at isn't clear to you. Whatever issues you have - make the time to comment and help improve the docs for everyone!
Nice initiative!.
When you take some topics in the CF livedocs such as "Integrating BlazeDS with ColdFusion". There is little to no information/working example available in those links.
Topics such as "Flash Remoting" does not have any info like where to get started.
Unlike Flex documentation where we use to get instant replies form the moderators (I guess they have more than one moderator) and they even used to email us stating whether our comment is approved or not with reward points!. What can't we have such option for CF docs too?.
Also I believe, CF Bug base could be made to accomodate the documentation errors / requests, which would help users to track their requests in an efficient manner.
-- Dave
It's a very interesting and useful initiative, very important for the popularity of CF.
The present documentation of CF is simply terrible and stupid. It's obvious that it is written by people having no idea on teaching. I have spent many years teaching programming to young programmers and I know.
1. The core of a documentation is to explain in a clear and short way that THIS DOES THAT !!! The examples of CF docu have long long useless blocks of code, having nothing to do with the e.g. func explained, and finally the reader can't see what the hell this code (and the func) does !!! He has to copy this code, paste it somewhere in CFBuilder, run the code in browser in order to see what the func does !!! The simple idea that below the code could be the result showing what the func did was too difficult for the docu writers. Just take a look in the short clear examples of SQL Server Books Online and and it's obvious what I mean.
2. The examples must keep the reader focused on the point, and the point is what the func does. The long blocks of code (code having nothing to do with the func) do exactly the opposite. From the other hand new and usefull funcs have too short examples, practically not helping at all. e.g. Why the function "IsStruct" needs 30 lines of code as example .... and the function "wrap" needs 4 lines ????
3. On the explanations of arguments their order is a mess and it's stupid. In some functions the order is the let's say "importance" of the arguments, and in other functions the order is ...alphabetical !!!! Just take a look in function "ArraySet" (order by importance) and "cfchart" (order alphabetical). In many optional arguments the documentation does not say what is the default value !!! (We have to guess it).
I could write much more, but I think the above are enough to prove that the documentation must be totally re-written.
Anastassios
Brian: There are docs on CFScript, what is supported, etc. I blogged about it before as it is a bit hard to find nav wise.
David: Well, to be clear, this is not MY initiative. I think it's a good one though. :)
Rob: I think that is the goal here -make time to take in the corrections.
I still use gotapi.com even though it's outdated (CF MX) the search is simply better, the functions are organized somewhat logically or more like other languages do it, assuming we only use CF is wrong.
A big issue is the organization of the site which throughout the aquisitions grew to a pretty messy URL scheme. The search engine ranking is absolutely terrible on some pages.
Google "coldfusion documentation" provides so many links to CF 7, CF 8 and even 6.1 where is 9? If you follow older links you often end up in a redirect mess from I guess an attempt to solve the situation or you end up with an error page with no way out.
Prime example of this (http://www.adobe.com/support/documentation/en/cold...) why is that URL linking to CF 8 resources? It's among the first result in Google too.
Once you eventually manage to find it, it's oddly laid out IMHO (http://help.adobe.com/en_US/ColdFusion/9.0/CFMLRef...).
I don't think I have EVER had a need to search for a function by alphabet. If I am looking at the documentation its for one of two reasons:
1) I don't know the name of the function and want to look for example at everything I can do to a string object.
2) I know the name of the function but forgot the syntax. In this case the way gotapi narrows it down as I type is simply stellar.
An a-z grouping is useless and/or akward in both cases.
In the first case, I don't know what I need so I won't find it, I resort to stackoverflow or google and use "How do I do x in CF" which usually lead me to a blog post (often yours ;-))
...
With the latest release of CF cfscript got a nice facelift and is now being treated as a first class citizen... the doc poorly reflect this unfortunately.
It's hard to find the equivalent from the tag page if not impossible. Example the cfswitch - http://help.adobe.com/en_US/ColdFusion/9.0/CFMLRef...
A link to the cfscript equivalent would be nice.
...
When I do manage to find documentation for what I want to do I often find the example ridden with typos, this is not acceptable, kudos for trying to correct the situation though.
Code example should be stored elsewhere and unit tested and simply injected in the documentation... it's as if no test are ran on the code used in the doc at all.
My latest occurence - SpreadsheetFormatColumn at: http://help.adobe.com/en_US/ColdFusion/9.0/CFMLRef...
First, what the heck is with the URL???
Second, look at the example:
// Define a format for the column.
format1-SructNew()
Like seriously? 3 typos in one line! Great average.
Forums within Adobe are very vague and most of the time the question is never answered. It would be great if the docs were tied to support forums with community and stronger moderator support. My 2 cents and slightly off-topic.
My biggest beef is not with the docs themselves (I generally think they're awesome), but with the presentation. I wish the docs were faster and easier to use. Speed them up with code optimizations, and then do some usability testing to see how to make them more user friendly.
On the other hand, I found hibernate docs lacking, especially on complex topics like implementing inheritance and so on... this is where examples and verbosity would be beneficial, but it's lacking, and so are the examples.
Where is the example output? Where are a list of use cases?
Contrast this with the Ruby documentation, while terse, is very explicit with examples. See this example for Array.delete_at: http://www.ruby-doc.org/core/classes/Array.html#M0...
Also, a separate domain / sub-domain optimised for search via Google so we can find the latest docs fast would be very useful and a big step forward. Do a search for 'coldfusion array' and compare it a search with 'ruby array'.
Cheers.
Also, whenever you click on a topic on the left pane, you tend to loose it because of the redirection.
But the actual reference at the top of the documents is fantastic. I use it daily and keep the PDF copy on my desktop for the dark and terrible times when my internet connection is down. The reference is brilliant, it's just some UI stuff that needs improving IMO
1 to 5 lines of code should be sufficient and will be easier for people to understand a lot more quickly. The output of the executed code should also appear under the code so people don't have to run the code to understand what it produces.
Many people are best at learning by example. However, some people find it difficult to read through large blocks of code that they may not understand (if they're new to the language or see no relevance in the example) so it's counter productive to force users to do it that way. Lots of very short examples of code is a better teaching method than one big example. It's significantly better if the output is shown underneath.
I'd also get Jake involved because I use CFQuickDocs interface much more than the actual Adobe site. It's quick, easy and the search interface rocks. It would be nice if Adobe adopted something like that as well.
--
Adam
I don't agree that the docs are useless without results shown, but I think there are some tags and functions for which example/results pairs would be extremely helpful. The next time I look one up, I'll make sure to note on the page what I mean.
If you're looking for large-scale improvements, then one thing I'd like to see is directed links from older versions to newer versions. This might help with the Google issue (where searching for content typically brings up CF8 or older docs): the little popup that says there is newer information available doesn't link to a specific CF9 page, so it really doesn't help me at all. What I want to see is the corresponding CF9 page. Yeah, it's going to be a big pain to link pages in past versions to pages in CF9 (or CFX or whatever) ... but there's obviously a lot of work going on to set up each version anyway, given the stark differences in documentation format (at least from our perspective), and if that's also something we can help with, so much the better.
I agree with Rob's point that corrections in comments should be incorporated into documentation more consistently. Other peoples suggestions of a wiki format sound interesting to me -- but a little scary too.
My own contribution is to mention that it took me a couple years before I noticed the tiny little arrows at the top for moving forward and backward a page in the documentation.
1. I'm still a little torqued about the move away from the left-hand tree navigation in CF8 docs to the alpha-grouping/inline navigation in CF9. But even the CF8 version could've been improved by grouping the functions and tags into functional categories: string functions, struct functions, etc., instead of outputting one big list.
2. The code snippets could be *way* better. And is there a safe way to run and edit/play with them inline? That would be so much better than cut-paste-run. At the very least showing the code side-by-side with the output would help a lot. I'm also giddy at the idea of having a shared "code snippets" library culled from actual use-cases attached to each function/tag.
3. The "live" concept of "live docs" is spotty at best. Adobe could do a lot more to encourage and take advantage of the kick-ass community of developers out there.
4. Linking to the documentation for the script version of a tag = win.
5. There should be better separation between the "theory/teaching" part of the docs and the "reference" part. Easy enough to hyperlink to one-another as necessary, but keep them functionally separate.
I also wanted to echo previous posters feelings about the inadequate examples. Take ListLast() for instance. I'm sure you all know that quote marks are required when specifying delimiters. There is absolutely no indication of this in the documentation though. the documentation goes on to provide three examples, But none of them show you how to indicate delimters, and no mention of includeEmptyValues is made either. I did a bit more research and found that these examples are exactly as they have been since CF MX 7...blatantly incomplete. Would your boss consider that acceptable if this was your job?
Here's something that I think would be fairly easy to implement, and would be useful for most people: Say I perform a search via Google for "IsValid" Personally I always get CF8 documentation as the first link, and the CF9 version of the documentation is nowhere in sight. SEO is not my issue with this though. If you navigate to the CF8 version of isValid and scroll to the bottom of the page you will see a small nav which provides links to each version of the CFDocumentation. But when I click on CF9 I am taken to the index. Why not take me to the CF9 "IsValid" Documentation instead of the index. If a user clicks on that link, I'm willing to bet 9/10 times they want to see the latest documentation on the tag they have searched for and not the index. This might not seem like a huge deal, but it would be a far more logical way to browse the documentation. Given that the target audience is developers, it seems silly not to spend the <1 hour it would take to implement.
I disagree. The docs clearly say:
"A string or a variable that contains one."
Now, you may make the case that a person may not know what a string is, but the docs have to assume some previous knowledge. Shoot, they don't explain what a variable is, right?
I concur though that an example showing a custom delimiter would be nice. May I ask why you didn't provide an example in the comments? Or make the reuqest?
To your last comment - I think that makes sense - and I do not see an easy way for folks to provide feedback to the system as a whole. I'll dig into that.
May I ask why you didn't provide an example in the comments?
[/quote]
It's not our job to do Adobe's work for them. CF is not an open source community-driven project (like Open BlueDragon for example), it's something we pay an awful lot of money for. And accurate, helpful and complete documentation is part of what we're paying for, but not really receiving.
That's perhaps why.
That might seem bloody-minded, but it's not unreasonable.
--
Adam
You get 5K pages of docs. For free. You don't pay for the docs. Just like you don't pay to download CF and run it, learn it, etc.
That person is Randy Nielsen and his email address is ranielse at adobe dot com.
[Add Comment] [Subscribe to Comments]