tracker issue : CF-4010693

select a category, or use search below
(searches all categories and all time range)
Title:

Improve quality of, marketing of and access to docs

| View in Tracker

Status/Resolution/Reason: Closed/Fixed/Fixed

Reporter/Name(from Bugbase): Adam Cameron / Adam Cameron (Adam Cameron)

Created: 06/22/2015

Components: Documentation

Versions: 2016

Failure Type: Enhancement Request

Found In Build/Fixed In Build: CF11_Final / docs

Priority/Frequency: Trivial / Unknown

Locale/System: English / Platforms All

Vote Count: 26

From http://blog.adamcameron.me/2015/06/what-id-like-to-see-in-coldfusion12.html

{quote}
I'd also mention they need to do a better job with the Wiki Docs...add in your CFScript blog post, steal it from you if they have to. Make the docs more accessible to everyone, not just a few people to update...there are a ton of people that talk about issues or examples of work via stack overflow or twitter or other places, do those examples ever make it to the wiki, doubt it. Also, they need to do a better job promoting the wiki docs, get more people using them, updating, them and talking about them...great they moved to a wiki, but if they never talk about them, what good are they.
{quote}

----------------------------- Additional Watson Details -----------------------------

Watson Bug ID:	4010693

External Customer Info:
External Company:  
External Customer Name: Adam
External Customer Email:  
External Test Config: My Hardware and Environment details:

Attachments:

Comments:

+1.........................................................
Vote by External U.
7023 | June 22, 2015 03:02:38 PM GMT
Agree with this one too. The CF documentation keeps falling behind and mistakes are not updated quickly. At least let the community contribute to the documentation if Adobe doesn't have the resources for it.
Vote by External U.
7024 | June 29, 2015 03:10:36 AM GMT
+1........................................................................
Vote by External U.
7025 | June 29, 2015 05:53:49 AM GMT
If we have full script support in CF11 and beyond, and we want more developers to use script as a good practice, then script examples need to be in the wiki docs. Either we need to have examples of script for each tag/function, or we need a link under a script table of contents item that links to community efforts on gitHub. Either way, the docs need updated to include more Script examples, or adding script support will be only for the highly skilled developer not the newbie just trying to learn or coming from a new language. Please do something to get more script examples into the Docs.
Vote by External U.
7026 | June 29, 2015 06:56:16 AM GMT
Wiki docs is a good start, but it still runs slow and I would like to see "components first" and "script first" type of documentation where we bring users into using CFCs and cfscript.
Vote by External U.
7027 | June 29, 2015 08:19:20 AM GMT
+1 definitely needed to help users move past "tags only" skills level.
Vote by External U.
7028 | June 29, 2015 09:03:04 AM GMT
We need better examples and references to things such as ways to convert legacy tag based code to cfscript based format
Vote by External U.
7029 | June 29, 2015 02:48:05 PM GMT
+1 definitely great help for developer
Vote by External U.
7030 | June 29, 2015 04:16:49 PM GMT
A system like Lucee has instituted that can be used to drive any number of output formats would be nice. Would be great to have the ability to generate a static HTML copy for offline use or a Dash docset automatically when docs are updated.
Vote by External U.
7031 | June 29, 2015 10:34:30 PM GMT
Great docs & tutorials are soo important for people starting with CFML
Vote by External U.
7032 | June 30, 2015 03:35:40 AM GMT
To encourage the use of script, in place of tags, provide the examples in script first and label them as preferred. Have a link at the top of the tag help page to the script alternative. More community involvement - blogs with examples. More participation with community and transparency of where the product is heading. Where are the Adobe Evangelist for ColdFusion hiding these days!
Vote by External U.
7033 | June 30, 2015 04:12:09 AM GMT
Microsoft has tabs on the docs page for c# and VB. How about tabs for tag syntax and script syntax? In any event, good examples and references are essential. Make links go to the most recent version of the docs and allow people to work back to previous versions.
Vote by External U.
7034 | June 30, 2015 08:55:09 AM GMT
People assume that time is a strict progression of cause-and-effect... but actually, from a non-linear, non-subjective viewpoint, it's more like a big ball of wibbly-wobbly... timey-wimey... stuff.
Vote by External U.
7035 | June 30, 2015 12:32:56 PM GMT
Please, when Torchwood comes to write my complete history, don't tell people I travelled through time and space with her mother! Sweet, maybe... Passionate, I suppose... But don't ever mistake that for nice. I'm the Doctor, I can save the world with a kettle and some string! And look! I'm wearing a vegetable! Don't you think she looks tired? I'm sorry. I'm so sorry. It is! It's the city of New New York! Strictly speaking, it's the fifteenth New York since the original, so that makes it New-New-New-New-New-New-New-New-New-New-New-New-New-New-New New York.
Vote by External U.
7036 | June 30, 2015 04:32:57 PM GMT
The docs do not appear to have changed in several versions. I would like to see them updated to reflect the changes to the tags and functions.
Vote by External U.
7037 | July 01, 2015 07:59:28 AM GMT
I definitely agree that the docs need to be modernized for Best Practices to help make ColdFusion look like a real language. I'm tired of arguing with other developers (that last saw CF in version 4) that CF has moved forward quite a bit as a language, when the docs themselves really don't do much to help my argument. Microsoft does do an excellent job with the way they present their examples, so tab-based wouldn't be a bad approach. Regardless, the docs also need better examples and a good description of how to transition legacy tag-based code to script-based. This alone would help break the notion that ColdFusion is just a tag language.
Vote by External U.
7038 | July 01, 2015 02:36:43 PM GMT
I agree with this as well, especially about expalining the scripting and adding examples. A nice table showing tags and their equivalent in script would be great too! The Internet is our "desk reference" and a great CF Wiki would be the best companion to a great product! If you're looking for volunteers, I would love to help with the cfchart section - it's in major need of more info!
Vote by External U.
7039 | July 01, 2015 05:39:23 PM GMT
This is one area that needs some serious attention. The docs are fragmented, often incorrect, lack sufficient examples, I could go on. When I work with new developers, they get so frustrated by the lack of proper and accurate documentation, it's a wonder ANYONE would pick up the language these days other than those of us that already use it.
Vote by External U.
7040 | July 03, 2015 11:12:50 AM GMT
I think the largest issue for me (being a CF developer since v3) is the lack of cfscript documentation. When I do a Google search, let's say for example "loop in cfscript 10" I get no relevant results. Rather end up resorting to Ben Nadel's for-in blog entry for CF 10. I like the idea of the tabbed UI. One for tag and one for script. Whenever possible I write services and controllers in script, as do many other people.
Vote by External U.
7041 | July 03, 2015 12:52:29 PM GMT
Lack of documentation is becoming a problem for acceptance.
Vote by External U.
7042 | July 03, 2015 12:57:00 PM GMT
totally agree - the examples are often poor
Vote by External U.
7043 | July 06, 2015 06:35:07 AM GMT
It's come to something when one small blog by one developer is higher ranked and better regarded than the official documentation.
Vote by External U.
7044 | July 06, 2015 06:37:26 AM GMT
totally agree - the examples are often poor
Vote by External U.
7045 | July 06, 2015 06:40:01 AM GMT
totally agree - the examples are often poor
Vote by External U.
7046 | July 06, 2015 07:44:03 AM GMT
Yes, do this...............................
Vote by External U.
7047 | July 06, 2015 09:44:04 AM GMT
One of the big "image" problems CFML has is that folks think it's about tags and "not a real language". If the docs focused on script-first for CFCs and used tags only for views, that could be addressed and CFML could be taken much more seriously by other developers out there.
Vote by External U.
7048 | July 06, 2015 11:24:18 AM GMT