Hi Ray,

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 would be nice if there was a CFScript reference on there. Maybe there is, but I can never find it.

I'll help Ray. I'm going to suggest that anyone that takes the time to correct a bad Example in the docs put the words "Viva Camden" somewhere in the text though. It will make looking for Quality code examples, much easier to find :)

:) I once got an Amazon gift card from Adobe 'cause I submitted comments to the CF doc. Thanks Adobe. :)

It would be nice if the Code Samples on the pages were GitHub Gists, and we could fork them if there are mistakes and Adobe could accept those changes. This way its not about just commenting, but contributing better, more correct, examples, and the process is more fluid long term. A lot of the code samples don't go over traditional use cases, so if CF folks could add code snippets - that would rock. I would like to see the docs be living, breathing and wiki like.

My biggest issue is that inaccuracies in the documentation often get noted in the comments but don't get incorporated back into the documentation. Sometimes they do, but not always. I think this could also be improved by providing a running update log of the docs so people can more easily tell when a particular document has been updated and what has been changed. Right now, you have to read through all the comments, then try to compare what was said there with what's in the docs to attempt to figure out what's accurate and what's not.

Hi Ray,

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

@Rob - using a wiki or something like github would help with the problem you mention.

Anastassios: That's a pretty strong opinion there. I think you are pretty off the mark here. I use the docs daily - specifically the reference - and it works great for me.

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.

Kudos for the initiative, it's always nice to see things being improved. I find the current state of the documentation pretty sad compared to other languages it doesn't even compare.

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/suppor... 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....

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...

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...

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.

And to add to that long winded post the structnew error I gave was flagged in the comments in January 2010 and the official doc never ammended.

Yeah, I've always been struck how Google can index the entire world and come up with the page that you're looking for better than the help manuals can search within themselves. Let's see.. Maybe a better way of viewing the documentation... I remember an old operating system that used to keep a stack of your commands so if you wanted to repeat a command, you would navigate the right-hand side of the screen (your history). Maybe incorporate some sort of history so that you can see what you've looked up before. Maybe have it be a more interactive document instead of a flat conversation from paper. In other words, "Here are the features that you haven't read yet". Without it being like clippy of course.

In general I like the docs if I'm looking for a specific property on a tag. Where I wish they were stronger is in support. If something has an unexpected result, you have to leave Adobe and end up on some Jedi website... jk.

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.

Ok, Ray, I did read your note above (even though most seemed to have missed it) that we are SUPPOSED to make these suggestions within the docs themselves, not here on your blog. And I have done so, but since this conversation is going here...

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.

Great initiative, Ray! One of the most irritating thing about the function examples is that they're overloaded with complex, often useless, examples when a simpler, cleaner example would have sufficed. Half the time I have to scan half a page of code in order to see where the function I'm reading about is being used! Perhaps simpler, cleaner examples can be provided in addition to the verbose ones?

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.

While I don't agree with some of the language that @Anastassios used, I do agree with the sentiment, especially in regard to the example code. Look at this example for dateAdd() - a very popular function we have all used a lot: http://help.adobe.com/en_US...

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/cor...

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.

A faster access to livedocs is what I will say a "Must have" thing considering the slowless/unresponsive pages of help.adobe.com

Also, whenever you click on a topic on the left pane, you tend to loose it because of the redirection.

@Anastassios, that's a bit harsh. The coding examples aren't very good a lot of the time, I'll give you that, and a rendered output on the page of what they might do would be a big help.

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

Bring back the old style of searching! The CF8 side-frame and localized search (not redirecting to random aggregate of user groups and the docs)

I agree with Anastassios that using long blocks of code to demonstrate how a function works is not the best way of teaching. You should not have to copy, paste, and run the code to see what the results are. It's the job of the documentation to show and explain the results.

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 second Rob's issue. The doc is commented on with a solution/correction but the doc itself is never updated.

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.

How about an API for online CF documentation?

Those of you looking for faster access to the docs, quicker/easier search functionality, a much cleaner/better looking presentation and more should give http://www.cfgloss.com a try. CFGloss is maintained by my good friend and fellow ColdFusion developer Joel Watson (existdissolve.com). I use it everyday and have learned that I can't live without it. It's a tremendous improvement of the Adobe version and contains the exact same content although he is considering adding customizable public and private user content. As far as I know it's supported by the most recent version of Chrome and IE9

I gotta say that Anastassios saved me posting my own long-winded and slightly abrupt analysis of livedocs. I agree 100%, including the tone used.

--
Adam

What does WACKs mean?

Web Application Construction Kit.

Cool. Thanks for that

I'm really impressed with the ruby documentation (even though the syntax makes my eye crosses). +1 about the code used in the Adobe CF documentation. Most of the time these don't exactly make sense and I have to really read these through to figure out what is going on. Another positive way to make these more usable would be to set up a way so you have two frames, code on left and a window on the right to display the results when you execute the code, whether it be a cfdump, cfoutput with clear labels, or whatever. There's a couple of jQuery tutorials that take this approach.

I think this is an outstanding initiative ... the online docs could use a lot of help, but Adobe people have only so much time, and there are a lot of us who can each do a little bit to make the docs better.

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.

Would it be possible to have collaboratively edited, wiki-style documentation?

I agree with Anastassios' points about code examples needing to be concise and to have any output displayed in the docs.

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.

Wow, hot-button topic. Everybody else pretty much covered most of my beefs, but what the heck, I'll add/re-iterate a few more.

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.

Sharon - to your last point - you know there is a separate Developers Guide versus the Reference, right?

I noticed they got rid of the iframes, which was a gigantic improvement. I would be inches from my answer, excitedly beginning to soak in the precious information I've been searching for when suddenly I am interrupted by an iFrame Loading.

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.

"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."

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.

[quote]
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

It's not bloody-minded, but it is short sighted. It's a bug. How in the hell is Adobe supposed to know about the issue if you guys don't tell us? Every single technical book I've read has had some form of a problem. It's natural - we aren't perfect. The Adobe docs have a perfect way of providing feedback so we can improve it. Choosing not to and complaining about how it isn't your job helps no one.

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.

IntermediateCFDev (btw, no need to hide your name here - I may not agree with all my commentors but I think we have enough respect here to not have to hide - if you feel otherwise, feel free to email me directly) - I checked into how someone could make a comment about the site as a whole. There isn't a form, but there is a person you can reach out to. (By the way, I already shared your feedback about what happens when you go from CF8->CF9).

That person is Randy Nielsen and his email address is ranielse at adobe dot com.

G'day Ray: a question and a heads-up.

Question:
What happened with this initiative? I've not heard any more about it other than this blog post.

Heads-up:
I cross-reference this article and mention your name (in a factual but not 100% flattering light, hence the heads-up) in an editorial I've just written on the state of the CFML Reference: http://adamcameroncoldfusio...

Cheers.

--
Adam