On finding what’s new in CF2018 (per the current state of the beta docs)

The public beta of ColdFusion 2018 was released today (Apr 16), and that’s great news. This is not a post about what IS new but instead about how you can find that out for yourself.

UPDATE and some great news on this

After I posted this entry, Saurav from Adobe did in fact address overnight nearly every concern I had raised in the original post here. Thanks for that fast response! 🙂 So, much of what I said below about “concerns” now no longer applies. Still, some of the other info may benefit readers, so I will not delete the post. Instead, I’ve crossed out things that no longer are issues, and I’ve tweaked a couple of sentences so they make better sense given these changes.

In the post announcing the public beta of CF2018, someone asked in the comments whether there were any “what’s new” docs. I started to answer his question (about how and where to find them), but then I observed some interesting challenges (and opportunities for improvement) about those current beta “what’s new” docs. So I’m turning it into this blog post instead, as it may help some readers evaluating CF and CF Builder 2018.

.I’m hopeful the CF team may address them for the next beta or final release (whichever it will be).

There are currently two “what’s new” docs

So first, about finding “what’s new”, there are two docs to consider (for now), both linked to from the page about the beta (which is itself currently linked to from that top right banner on the portal here). 

There you’ll see first a “what’s new” doc,which is a one-page overview of a dozen key new features they’ve chosen to highlight.

Second and more important there is what they label (currently) as “ColdFusion 2018 Feature Guide”, and THAT doc is the kind of “what’s new” or “release notes” that most would be seeking to find about “what’s new  It’s (in this beta) 62 pages, including screenshot of most of the major new things.

(BTW, both docs mention CF Builder updates, with a bit more detail as the last section, currently, in the larger doc. Really, nor much has changed in CFB, it seems.)

Some challenges with the what’s new docs

And while I’m thrilled as always to see the meat of the larger doc of course (and the smaller one has value as a quick summary), there are a few challenges with both it and that brief summary list.

First, sadly there’s (currently) no table of contents for that larger doc. The larger docs nearly follows the order of the one-page “what’s new”, but I’m not sure why they didn’t just create a TOC at the top of the larger doc and then extract that as a one-pager to stand as its own as a brief summary doc.

For now, they are not quite in sync. For one thing, something listed in the larger but not in the smaller is “Data type preservation”. There is also much more to the REST enhancements in 2018 than the one aspect of it listed in the smaller document. Also, the title used for a given feature in each doc doesn’t always match: “Filter fields from JSON request” in the smaller doc is listed as “JSON Field Projection” in the larger doc.

Again, I really hope someone will reconcile these things, and not only create a better TOC for the larger doc, but also add some heading numbers (or better formatting) to know what things are subsections of other things above them, as it’s not always clear from the section title alone. (And this is I keep saying “currently” here, because things will change over time while my post will remain for readers to see in the future.)

The other docs about CF2018

Finally, notice that there are several more available docs (listed in that “documentation” column on the beta page).

Some go into more detail on new things (like one each on the new Performance Monitor Toolset (36 pages), and the new Automated Lockdown Guide (11 pages), while others go into known issues (5 pages), issues fixed (3 pages), systems supported (4 pages), and system requirements for CF and CFBuilder (1 page each). These are of course also all important when considering “what’s new” in CF2018 and CFBuilder 2018.

One other “doc”, not currently listed

Before ending, I’ll note that there is one other “document” linked to from within the larger “what’s new” doc but which is NOT currently listed on the page showing all the other beta docs. It’s about the new “Named Parameters” (or some may want to say “named arguments”) feature, which is mentioned only very briefly in the larger doc.

With CF2018, you can now call CFML functions using *named* arguments (rather than the old positional one previously supported). The list and their values are in that document. It’s a 12-page PDF with no title or discussion of the feature. I suspect at some point there will just be a new section in the CFML Reference listing these. Maybe that’s why why they have not listed it in the “documentation” column, but I wanted to point it out for completeness sake.

About that curious “documentation” column

Finally, I hope the CF team might reconsider the way that the docs are currently offered on that beta overview page. As I said at the outset (and you will find, at least if you visit the page today), the docs are offered in a column (headed “documentation”) which appears to the right of the “downloads” column.

That tabular presentation seems a curious choice, as it can be read to convey that there’s a connection between the rows in the downloads column on the left with the values in the documentation column on its right. But of course there’s no connection. (Same with the “Report a bug” column.

So, that’s quite a few things I’ve mentioned in this post as opps for improvement, and sure, many are just opinion, and not all (Adobe or other readers) will agree with each suggestion.  Again, I’m hopeful that in time at least some of the more important/consistency tweaks may be taken on-board.

Again, thankfully they made the changes last night, but I leave the rest for whatever value it may offer readers. Comments welcome, of course. One quibble remains, from my original post:

As for the ordering of information on that beta page, I would think instead that the links to the docs should simply be one section at the top of this page (since they ought to read or at least clearly know they are there before downloading it). Then it could offer a section on reporting bugs, and then finally a section for the downloads (and I am intentionally proposing they leave the link to report bugs above the downloads, as that too increases the chance that people will notice the option before proceeding to download.) Just my opinion, of course. 🙂 Hope all this helps make the docs more and more useful for everyone.

19 Responses

  1. Thank you for the article. I really wish they would follow WCAG2 standards, then the tables wouldn’t exist and the bad color combinations would probably not exist. It really is a poor presentation choice (sort of like Tracker).

  2. Hi Charlie,

    Thanks for reporting the bugs. We have inserted a Table of Contents along with numbered headings and have also modified the smaller document.

    We have also changed the tabular layout of the items so that it is in a better readable state.

    Please provide your thoughts on this.

    Thanks,
    Saurav

    • Thanks, so much, Saurav. You’ve addressed nearly all the items I listed, in both how things appear in the beta page, and in the two primary what’s new guides.

      Just a couple of minor quibbles that remain, and one new one:

      1) First, I forgot to say this yesterday, but the smaller guide’s first point should say it’s the CF *Admin* that has a new UI, not CF itself. (The larger doc gets it right in the first section head.)

      2) As for some things that remain, the JSON field feature is still named differently in the two docs: in the larger guide, in 5.7 it’s “JSON field protection”, while in the single-page doc it’s still labelled “JSON field filtering”.

      3) Also, the order in the two docs is still not in sync, with some major and minor points in a different order in the smaller doc than they appear in the larger.

      I realize that the small one has some extra text for some points, so that you can’t just “make the small one out of the TOC of the large one”. And perhaps the order in the smaller one stresses some importance by its ordering, but I would suggest that the larger doc then be made to follow the order of the smaller one.

      4) Finally, another thing I didn’t think to ask yesterday: is it really intentional that the main beta page lists first the info about contributing to the portal? I’d really think that was not the primary thing. Indeed, one thing I had proposed was that it seemed having the docs first was more important than having the download links.

      Some may disagree, of course, wanting to “get to the files”, but this is a prerelease, and people should know of (if not read) the docs before jumping at the downloads. 🙂

      But I’d think logically it should be docs, then downloads, then contribution info.

      Again, I really appreciate your quick response to the original post. In fact, I want to edit it, to indicate how much of it has been addressed already. But in the past I found that if I edited a post here, it will be “removed” while it awaits “approval”, which could confuse folks who may look for it–and you may even find that you can’t locate it to offer another reply.

      Still, maybe that problem has been resolved, so I’ll give it a shot. Worst case, you may see this and could nudge whoever is approving them. 🙂 I realize it may be overnight if they are working on India hours.

      • Charlie, can you try to editing your post now?


        Again, I really appreciate your quick response to the original post. In fact, I want to edit it, to indicate how much of it has been addressed already. But in the past I found that if I edited a post here, it will be “removed” while it awaits “approval”, which could confuse folks who may look for it–and you may even find that you can’t locate it to offer another reply.

  3. Hi Adobe,

    Regarding “But in the past I found that if I edited a post here, it will be “removed” while it awaits “approval”, which could confuse folks who may look for it”:

    I’ve experienced the same. Editing a post causes its removal until approval.

    Can you please whitelist us, so that we aren’t affected by this removal/approval process?

    Thanks!,
    -Aaron

  4. Hi Charlie, Stephen, Saurav and Anit,

    Thank you very much for getting the Beta page easier to read, and getting the download links into bulleted lists.

    I agree the order should be:
    1) “Documentation”
    2) “Report a bug”
    3) “Downloads”

    IMO, the Beta’s ROI would improve if prospective beta testers are clearly aware of #1 & #2 before reaching #3.

    Thanks!,
    -Aaron

  5. Hi Charlie,

    I’m sorry to hijack your thread, but didn’t want to create a separate discussion for the following point:

    The Beta page’s “View all Discussion” button should probably say “View all Discussions” (plural instead of singular).

    Unless, of course, there will only be 1 discussion =P

    Saurav Ghosh and Anit Kumar Panda can that be updated?

    Thanks!,
    -Aaron

Leave a reply

Related