Adobe ColdFusion Docs team, there's a better way...

I'm not a fan of the approach the Adobe ColdFusion (ACF) documentation team has moved to with documentation for the recent versions of their product.

A bit of background

With the recent (late May 2014) release of ACFv11, there are now three versions of ACF in which I have varying degrees of interest: 

• v9: we are in the final stages of moving our last app from a shared v9 server to one of our dedicated v10 servers,
• v10: our entire dev environment is based on v10, and all of our apps with the noted exception above run on v10 in production, and
• v11: the recent release we've watched from a distance as we weigh whether to continue with ACF in the future or shift to Railo as our CFML engine.

As a team, we've been on ACF since its Allaire v4 days, and have historically had multiple versions in play across our development and production environments, so the above situation covering three versions is very typical for us. In fact, having all of our dev and production environments based on a single version of ACF as we (almost) do now represents the first time in close to 10 years we've been able to achieve this. I don't believe we are unique in this: any developer moving between versions of the product (or even considering such a migration) will be working with at least two versions of the language and/or the documentation before and during their migration effort.

In addition, I built and continue to maintain a CFML language mode for ActiveState's Komodo IDE and Edit editors, providing syntax highlighting and tag/tag attribute completion. The tag/tag attribute completion is specific to each CFML version, allowing the user to designate which version of the language is to be used as the basis for which tags and which attributes are to be provided as options to the user. I rely heavily on version-specific documentation to build each of these version-specific implementations.

The problem with the current wiki approach

In versions of ACF up through v9, each version had comprehensive documentation sets available both online and as downloadable PDFs. Each of these documentation sets were separate and distinct, and the online versions made it very straightforward to shift between versions. With v10, however, there is a downloadable PDF version of the documents (thanks to Adam Cameron for pointing me toward those) but the only references to it I can find are not easy to find (search the wiki for "archive" -- how obvious is that if you are looking for CF10 documentation?). The online version of the documentation is maintained as part of a wiki that does not contain discrete sections for different versions of the product or language and for the most part appears to be focused on v11.

The old version of the online docs has the tremendous benefit to the user of being crystal clear as to what capabilities are available in that version of the language (e.g., which attributes are available for a given tag, what functions/function arguments are available). If I am working on an app currently running on version "x" of ACF, I typically want to see only the version "x" documentation for that tag.

The current wiki-based documentation set, however, does not have that clear distinction between versions of the product or language. This makes differentiating between versions for tags, attributes, supported attribute values, functions, etc., in terms of what is valid and supported between versions far more challenging and error-prone than in previous versions. If I care about the v10 implementation of the cfzip tag, for instance, I have to either use the off-line version of the docs or make sure I look at the "history" portion of the relevant tag page and then mentally remove the new attributes added for v11 ("password" and "encryptionalgorithm", in this particular case) as I scan down through the attribute documentation -- particularly given that there is nothing within the description of the attributes indicating their recent addition in v11).

A better approach?

It seems to me that a better approach would be for separate, discrete version-specific sections within the wiki. The language reference -- along with the supporting documents identifying additions, removals, and deprecations -- is one example of where this would make the documentation much easier to use. The v10 portion of the reference would always be specific to v10 and would not (should not?) need to contain any v11 content. The v11 portion of the reference would presumably start as a clone of the v10 portion of the documentation, and could evolve along with the language as v11 was developed. As work on v12 is started, the v11 portion would be cloned as a draft and evolve independently from the sections covering previous versions.

The current wiki approach is likely to get more and more unwieldy as additional versions of the product and the language are covered within the current wiki structure. Take the page listing deprecations and removals as an example. Besides being in drastic need of updates as of this writing for completeness and currency with v11, this page -- based on its current structure -- will get more and more unwieldy as additional versions have to be covered: more rows to cover features being deprecated or removed, and more columns for subsequent versions? The current approach just does not seem to scale for pages such as this.

Note that this is not a problem with the use of a CMS or wiki for the documentation itself as much as it is a poor decision, in my opinion, on how to structure the documentation within the tool they selected.

Finding documentation for earlier, but still-supported, versions of a product should not be difficult but in this case it is getting harder. I'd like to believe the ColdFusion documentation team will see the light and restructure the documentation set before it collapses under its own weight and degenerates even further in terms of being usable and useful.

And the off-line docs?

The current wiki structure -- where it seems to be focused mostly on the current language version -- also raises the question for me as to whether a similar set of downloadable v11 references will be made available now that the product is available or as the wiki gets refocused on v12. That's a separate but important and relevant question. I hope they do, as those downloadable PDFs have repeatedly proven invaluable for me and my team.

A Gotcha with Enabling J2EE session in Adobe ColdFusion on Apache Tomcat

I've spent a bit of time over the past month or so playing with setting up a couple of my development systems to run Railo and Adobe ColdFusion 10 on a stock install of Apache Tomcat 7. In the case of ACF10, my interest in running on stock Tomcat is based on a desire get away from the custom-built and now outdated version of Tomcat Adobe (unwisely, in my opinion) bundles with ACF10. This past week I bumped into a bit of a gotcha that took me quite a bit of time to track down and solve. In the hopes of helping others avoid this same problem and so that I don't forget it, I'll share what I ran into and how to solve it.

The symptoms I was seeing were that as soon as I enabled J2EE sessions in the CF administrator and then subsequently stopped Tomcat for any reason, Tomcat would no longer start cleanly,it was no longer bringing up the context running ACF, and because it was not starting cleanly it would also not shutdown cleanly. As weird as this seemed (and sounds, I realize), this was very repeatable. I had it down to something I could reproduce in under 5 minutes: set up a clean new Tomcat install, deploy ACF10 on it via a WAR file, sign into the CF admin, enable J2EE sessions, stop Tomcat... and it would no longer start. There was nothing in the ${CATALINA_BASE}/logs/catalina.out log file indicating what was wrong; it just looked like as Tomcat began starting, it would hang.

It seemed like something about turning on J2EE sessions in ACF10 was breaking Tomcat. Based on a suggestion from a co-worker, I removed write permissions for the user under which Tomcat was running from all folders under ${CATALINA_BASE} except the ./logs/ and ./webapps/ folders, in an attempt to see if I could determine where the breakage was occurring. On starting Tomcat, I noticed a complaint in the ${CATALINA_BASE}/logs/catalina.out log file about not being able to write to folder ${CATALINA_BASE}/work/Catalina/localhost/_. Looking in that folder, I found a file named SESSIONS.ser and doing a bit of Googling, I came across a short blog post dealing with session persistence across Tomcat-restarts.

I'm not going to pretend that I know why Tomcat would have session persistence enabled across restarts, or why I might want to persist sessions across restarts (I really can't come up with a scenario where I would want that), or why enabling J2EE sessions in ACF10 would seem to break this persistence... but clearly it does. To disable this persistence, the context(s) within Tomcat on which ACF10 is enabled need to include a session manager component specifically configured to disable this persistence:

<Manager pathname="" />

This is touched upon in the Apache Tomcat docs here.

Recap: Adobe ColdFusion Summit 2013

I'm going to try to capture my thoughts on Adobe's recent inaugural ColdFusion Summit 2013 conference. You'll find lots of my own opinions here and a bit of rambling. There may or may not be much of value to you as a reader... continue at your risk.

Overall Impression

For the first year of a new conference, I felt like the conference organizers did a decent job of pulling it off. Acceptable facilities, good food, good reception, good WiFi, good breadth and depth of topics to choose from and delivered by a combination of both known and previously-unknown (to me, at least) speakers. The conference itself had a few rough spots (more on that below). I came interested primarily in hearing Adobe's position on ColdFusion's future and walked away convinced that at least the Adobe CF team itself is convinced CF does have a future. I remain concerned about certain aspects of that future and not entirely convinced in the CF team (but that's a subject for a separate blog post).

Facilities and Conference Stuff

I should preface this with the statement that I am not a "Las Vegas person" -- very little about Las Vegas itself is appealing to me. I'm also not crazy about big resort hotels, and the Mandalay Bay Resort is nothing if not that. I would be perfectly happy in a smaller conference facility somewhere else.

Signage is definitely not the resort's strong suit, and we spent 45 minutes wandering around Wednesday evening looking for the early check-in location and asking people that seemed to be associated with the hotel and/or convention center where it was before someone finally pointed us in the right direction, only to find out they didn't have our t-shirts so we gave up and went to get dinner and just waited to check in Thursday morning. Check-in itself on Thursday morning was simple, smooth, and fast. If you are going to offer some sort of early check-in, make it easy to find and have the stuff ready, or don't bother.

The session and keynote rooms were sufficient but only barely so: sub-par audio, small screens, and poor room layout all made for challenging settings for both speakers and listeners. I've had to present in rooms like those, and it is challenging at best. I did like the classroom sort of setting where everyone was sitting at tables, and the decent WiFi coverage was a pleasant surprise. Only one of the rooms had power at the tables; it would have been nice for that to be more widespread. Having all of the presentation venues very close to each other was a plus.

At several points in both the opening keynote and the closing comments delivered by Adobe reps, they touched on having to cap attendance at 500 and how that number was significantly above what they originally had planned for. I left wondering if the juggling to accommodate a larger-than-initially-anticipated group of attendees resulted in some juggling on the facilities side and contributed to room layouts, etc., that left quite a bit to be desired.

I appreciated the single-sheet agenda handed out at check-in, although I would have liked for the single-sheet agenda to have included the names of the speaker(s) for each session. The conference Web site was acceptable, although I never did figure out why they wanted us to set up a schedule there... and the session-scheduling part of the Web site was pretty clumsy. I couldn't install the conference app on my phone, but no one I talked to using the app on either Android or iOS was impressed with the app or even had much positive to say about it.

In general, the length of the sessions, breaks, and the overall length of each day was about right. Very few of the sessions I sat in on, however, left any time for questions at the end; this may be something the organizers and content committee should touch on with presenters in the future or extend the sessions slightly to accommodate questions. (I would be curious to hear opinions from the presenters themselves on this item.)

My impression is that the conference organizers hadn't made plans to either record any of the presentations or provide a central place from which presenter slide decks could be downloaded; the second of those two was a particularly surprising decision or oversight.

Some of the stumbles were surprising given that Adobe has been involved in conferences larger that this for many years. If there are to be subsequent versions of this conference -- and it seems pretty obvious from the closing wrap-up that the intent is that there will be -- and if the conference organizers can retain the generally high quality of most of the content and if the conference organizers can address some of the facility-related shortcomings, this could be a very good conference in the future.

Session Recap

A few thoughts on the sessions I attended...

Day 1 keynote (Ben Forta, others): Disappointing. Ben Forta started with a quick look back at the history of CF and at some of the successes and failures in CF along the way, talked a little about where he sees things headed, that CF has now been dead for more than half its life and continues to grow and evolve in spite of being dead, and finished with a few of his own opinions on what CF's strengths are and where it should be headed. Ben gave way to a couple members of the Adobe CF team and the keynote -- for a keynote, but particularly for a day 1 keynote of a new conference -- went off a cliff. It turned into a detailed demo including code, etc., that felt like it had largely been thrown together and had not been rehearsed or screened to fit into the allotted time. This was not opening day keynote stuff, either in content or in presentation. More concerning to me, though, was the contradiction between BF's take on where things should be heading... immediately followed by lots code and demos of the CF team's CFCLIENT efforts. I'm not a fan of the CFCLIENT idea, and nothing I heard in sessions or follow-up blog posts has convinced me that CFCLIENT and the effort/resources Adobe is pouring into it are a good choice. To have that contradiction so visible within the content of the opening day keynote reinforced my own concern that Adobe and the CF team don't see the importance of some of the "soft side" of CF: the value of communication and the importance of getting the message right. I've increasingly felt that way for the past couple years and this conference repeatedly reinforced that concern. The keynote itself suffered greatly from the combination of terrible acoustics, high A/V system volume, poor physical layout, small screens, and speakers with accents speaking way too quickly. There were portions, even during BF's portion, where I simply could not understand what he was saying and it was even more challenging with the other members of the CF team. In watching the #CFSummit2013 twitter feed during and after the keynote, I know I'm not alone in those concerns or in my take on the keynote.

Language enhancements in ColdFusion Splendor (Vamseekrishna N of the Adobe CF team): Poor. Illegible slides (yellow text on white background rendered at a small size, anyone?), almost entirely a repeat of stuff from the keynote (which admittedly should not have been in the keynote in the first place), poorly organized and presented content, and struggles with tools. (Seriously? A CF team member that doesn't know how to change the font size in Adobe's flagship CF development tool?) Poor audio, bad room layout, small screens. In terms of the changes coming in the language itself, I see some things I like: member functions, something closer to full coverage of the language's capabilities in CFSCRIPT, better/more complete JSON handling.

Java Integration (Dave Gallerizzo): Good intro presentation to what you can do with Java both in using existing Java libraries and in invoking CF stuff from within Java. Good presenter. Nothing really earth-shattering or eye-opening for me there.

What's New and Different in ColdFusion 10 on Tomcat (Charlie Arehart): Very good. Charlie is one of the rare speakers with both extraordinary knowledge and the ability to share that knowledge effectively in the setting of a conference presentation. I've used Tomcat for the past couple years outside of just in ColdFusion's stack, but even so there were a couple of nuggets from his session that were new and potentially valuable to me.

Advanced OO in ColdFusion (Scott Stroz): Very good. Scott's usual blend of expertise and humor made for an informative and enjoyable session. Despite being assigned to a huge room, Scott has enough presence, clearly is a sufficiently experienced presenter, and structured his slides in a manner that the setting itself did not detract from the presentation.

Preview: ColdFusion Splendor (Rupesh Kumar): Good. Lots of overlap with the technical detail already covered in the keynote and in the earlier session on coming language enhancements, but I felt like Rupesh did a much better job of covering the relevant content at an appropriate level and in an understandable manner. Realistically, though, I think the CF team would have been better served by having this be the primary session touching on what's coming in the next version of CF here and avoiding the duplication of content in at least three sessions. One slightly surprising thing that came out of this session was when I asked about approximate release dates for the next version, Rupesh's response indicated that it would be "sometime next year", representing a pretty significant slip from earlier communications.

Reception: Good. Good setting, free drinks, and decent appetizers for a couple hours in one of the restaurants in the conference resort. Great setting to just sit and talk, as well as to circulate. Enjoyed a short conversation with Elishia Dvorak of the Adobe team, and appreciated the fact that someone from the Adobe team was making an effort to find out who was at the conference and what they were working on.

CFHour session (Scott Stroz and Dave Ferguson): Really poor. I've listened to their podcast for the past few months and typically enjoy (or sometimes just tolerate) their mix of information, opinions, commentary, and humor. This one seemed to take a big turn south when it became known that they were not going to be able to record the session. Any apparent attempt to provide value seemed to go out the window at that point. I should have just gone and gotten another beer. Funniest part was Jason Dean's brief appearance. Some interesting back and forth with the audience when the subject of the recent security event involving someone taking copies of source code for Adobe products was raised, but still no word of any sort from Adobe or the CF team on what was taken, what they are doing in the aftermath of the event, or whether they believe this event represents any sort of additional security concern for CF users.

Side note: Earlier in the day, I had stopped to ask a couple questions of one of the CF team members at their table set up in the hall. I posed the question of when Adobe would be making further information available. The team member immediately turned to look at one of the more senior team members who came over and recited almost verbatim the line that as long as I didn't have the CFIDE stuff publicly available and had my server locked down, there were no known risks. This isn't even the question I asked... so clearly they had been directed to simply recite this line and try to move on. When I asked a second question about support for Apache 2.4, I got a shrug and a "we're not sure". OK, then... oh-for-two. Time wasted; get some lunch.

Day 2 keynote (Avi Rubin): Good. Interesting discussion of software and information security. Not specifically CF-focused, which generated some Twitter traffic, but still absolutely relevant to those of us working as within the application development space. Very enjoyable change of pace.

NoSQL (Dan Wilson): Very good. Really approachable introduction to NoSQL through MongoDB. Good breadth and depth for an intro. Good mix of technical content, experience anecdotes, and Dan's dry sense of humor. I've never played with a NoSQL back-end for data storage, but after sitting through this session, I plan to look hard at it for certain portions of the less relational information we're collecting and maintaining in some of our applications. Great slides, even for code content and even taking into account the poorly laid-out presentation space.

Closures (Adam Tuttle): Very good. A great introduction to the concept. Really liked that his preso was based on Reveal.JS and was available for us to follow along with on our laptops while he went through it, completely eliminating any concerns about visibility/legibility of code snippets, etc. I've used callbacks and anonymous functions in jQuery more than in CF, and even occasionally some simple closures in JavaScript, so very much enjoyed digging a little deeper into this. Very much liked Adam's preso deck and appreciated his understated approach in presenting.

Amazon Web Services (Brian Klass): Very, very good. Probably the most eye-opening session for me of the conference. Brian did an incredible job of cramming a very broad and very deep subject into an hour. We've not done anything with moving toward AWS or any other cloud-based infrastructure yet but have been toying with a move in that direction for a couple of reasons. This was a real eye-opener for me as to just how different hosting in that environment would be in terms of architecting and maintaining infrastructure compared to just standing up another physical server in our current network DMZ. Great slides in terms of content and legibility, and a very knowledgable, polished presenter.

CF911: Server Troubleshooting (Charlie Arehart): Very good. Typical Charlie Arehart presentation: great content, great slides, great delivery. As has always been the case when I've attended one of his sessions, I walked away with several specific items I will go dig into. I'm convinced Charlie is one of real gems of the CF community with his experience, knowledge, ability and willingness to teach and share, and his personality.

Advanced Caching (Rob Brooks-Bilson): Good. I figured this would be sort of a throw-away for me, as I sat in on it simply because there was nothing more interesting on the agenda at that point... but I have to say I was impressed. Very interesting presentation on what's becoming possible with some new products to enable caching on a huge scale. Not really relevant -- at the huge scale discussed in Rob's presentation -- to my current work, but it was interesting enough to keep me awake (despite being exhausted) and convinced me that I do need to look into caching at least a little bit.

Closing remarks (Adobe rep; no idea who he was and he didn't introduce himself): OK at best. Nothing earthshaking or new to wrap things up. Reiterated that there is growth in the Adobe CF customer base (at least when measured in new customers) and he emphasized that this was new customers, not just new license sales. Also touched on Adobe's efforts to support the CF community through their and others' education initiatives.

Summary

The conference itself came off reasonably well and has potential to be even better in the future. I certainly came away feeling like attending was both time and money well-spent. Some very, very good presentations with real value for me and my team. I continue to be concerned about Adobe's management, support, and vision for the evolution of the CF product, perhaps less so than 6 months ago, but still concerned. I'll write more on that in the near future.

Lost in translation?

As a follow-on to my earlier post related to prematurely-expired chart images in Adobe ColdFusion, I came across this link: http://www.elliottsprehn.com/cfbugs/bugs/86743

The bug is clearly related to what I am wrestling with, although this bug appears to be more related to orphaned image files piling up. What caught my eye initially was the comments about how at least one of the settings in the CF Admin UI was basically useless the apparent lack of documentation of this configuration file.

Out of curiosity, I wanted to see if this particular bug was ever resolved -- curiosity driven in large part because I am wrestling with this same sort of problem and could easily see this bug (if still unresolved) impacting my servers as we play with the configuration settings to get past the expired chart images.

Guess what? This bug does not appear to exist in the Adobe ColdFusion bug tracker in any form... no matter how I search, I can find no reference to it in their current system: not by content, by author, by ID, or even by date. I can find bugs prior to this and following this but not this one. Which raises a really interesting question: how many other issues like this, that a user of their products troubled themselves to investigate and document, got lost or dropped?

I don't really know what Elliot's system is drawing information from, but it seems like it might be worth Adobe taking a second look at what might have gotten lost.