MOST IMPORTANT!! Enhancing ColdFusion Documentation for AI Integration: A Call to Action

[chandras87981082]

Dear ColdFusion Community,

Allow me to introduce myself. I'm Chandrasekhar Sahoo, a passionate ColdFusion developer with 7 years of experience working with CF technologies. Though I'm new to the Adobe community, I've long admired the power and flexibility of ColdFusion. Today, I'm reaching out to discuss a critical issue that I believe will shape the future of our beloved language.

As we navigate the rapidly evolving landscape of software development, it's become increasingly clear that artificial intelligence (AI) is not just a buzzword but a transformative force in our industry. Today, I want to discuss the critical need for ColdFusion to adapt its documentation to be more AI-friendly, ensuring our beloved language remains competitive and relevant in this new era.

Why AI-Friendly Documentation Matters:

1. AI-Assisted Development: AI coding assistants are becoming integral to modern development workflows. They can significantly boost productivity by offering code suggestions, explaining complex concepts, and even generating entire functions. However, these AI tools rely heavily on high-quality, structured documentation to provide accurate assistance.
2. Learning and Onboarding: AI-powered chatbots and learning tools can dramatically reduce the learning curve for new ColdFusion developers. With proper documentation, these AI assistants can provide instant, context-aware help, making ColdFusion more accessible to a new generation of developers.
3. Maintaining Relevance: As AI tools become more prevalent, developers are increasingly likely to choose languages and frameworks with strong AI support. If ColdFusion falls behind in this area, we risk losing mindshare and potentially dropping in popularity rankings.

Current Challenges:

1. Documentation Structure: The current ColdFusion documentation, while comprehensive, isn't optimized for AI consumption. AI agents often struggle to index and understand the content effectively.
2. Interface Issues: Users report that the documentation interface is laggy and glitchy when accessed by AI agents, hindering their ability to process the information efficiently.
3. Lack of Machine-Readable Formats: AI systems benefit from documentation in easily parsable formats like JSON or XML, which our current setup doesn't prioritize.

Proposed Solutions:

1. Restructure Documentation: Organize content in a more hierarchical, consistent manner that's easier for AI to parse and understand.
2. Improve API References: Ensure all functions, tags, and components are documented in a standardized format that includes clear descriptions, parameter details, and usage examples.
3. Provide Machine-Readable Formats: Offer documentation in formats like JSON or XML, alongside human-readable versions.
4. Enhance Search and Indexing: Implement better search functionality and indexing to help both humans and AI quickly find relevant information.
5. Regular Updates: Commit to keeping documentation up-to-date with each ColdFusion release, ensuring AI tools always have access to the latest information.
6. Community Involvement: Encourage community contributions to documentation, leveraging the collective expertise of ColdFusion developers worldwide.

The Benefits:

By improving our documentation for AI consumption, we stand to gain:

1. Increased Adoption: Making ColdFusion more accessible to AI tools could attract new developers and retain existing ones.
2. Enhanced Productivity: Developers using AI-assisted coding tools will be more productive when working with ColdFusion.
3. Competitive Edge: We'll position ColdFusion as a forward-thinking language ready for the AI-driven future of development.
4. Community Growth: A more accessible language could lead to community expansion and more diverse contributions.

Call to Action:

I urge the Adobe ColdFusion team and our community to prioritize this initiative. We need to form a task force to assess our current documentation, benchmark against AI-friendly docs from other languages, and develop a roadmap for improvement.
Let's ensure ColdFusion remains a top choice for developers in the age of AI. Our ability to adapt to this new paradigm will be crucial in maintaining and growing our position in the programming language landscape.

I look forward to hearing your thoughts and discussing how we can collaborate to make this vision a reality.

[Charlie Arehart]

Heck, let's get it at least human-friendly! I've lamented (publicly) for years how there are literally THOUSANDS of pages of CF docs (especially the Developer Guide) that few ever find in their own. And though search engines (and AI) crawlers might find and drop people into them, they often lack any visual indicators to a) reflect where they are in the context of other related content, let alone b) visual indicators to go forward or back (or up or down) to such related content. 

Again, if such things were fixed for humans OR for AI consumption it would certainly be an improvement.

Good on ya for elaborating things. Let's hope there's further consideration or response from those in a position to do something. 

[chandras87981082]

Charlie,

Your response truly made my day! I've long admired your work, and it's heartening to see you share these concerns.

You're absolutely right - the documentation needs a human-friendly overhaul first. I've often (if not always) found myself lost in those documentation pages, wishing for better navigation and context.

Your ongoing advocacy for improvement is inspiring. Let's hope this conversation sparks some real action.

Thank you for your insights and continued dedication to the ColdFusion community.

Chandrasekhar

[Charlie Arehart]

You're very kind. Thank you. 

[BKBK]

Thanks for that, @chandras87981082 . Your call-to-action is loud and clear.

[James Moberg]

I reached out to the ColdFusion account on Twitter/X back in Dev '23 regarding this and didn't get any response.
https://x.com/gamesover/status/1731027099459453057

I attempted to use an AI engine to parse one of the older Adobe PDF books... and it failed.  The Adobe online documention can't be easily spidered. I often have questions regarding functions that aren't clear in the existing online documentation.  I hope that this changes.

Sidenote: I just noticed that discussions can be upvoted.  Please go to the top of this page and upvote this if it's important to you.

[BKBK]

@James Moberg , as far as I can see, one cannot upvote the original post, only the responses. 

[James Moberg]

Hmm... not sure about your experience.  Here's a screenshot from my desktop Windows 11 Edge browser.

The box initially displayed a "1".  After I clicked it, it displayed a "2".  (In the source code, it's has a "custom-kudo-message-component" class and teh title attribute (for me) is now "Click here to remove your vote from this post".)

 

[BKBK]

Thanks, @James Moberg . You don't say!  I always thought that that is a "like" button. 🙂
I don't remember seeing a link-title when my mouse hovered over it (on Chrome).

[James Moberg]

The HTML element's "itemprop" is "upvoteCount" and has a class up "upvote-icon".  Maybe it's just semantics.

I found out why there's a discrepency.  After voting, the DIV with the text "Voted" and title attribute "Click here to remove your vote from this post" is only displayed if your browser's page width is less than 768 pixels... otherwise it's hidden using a CSS breakpoint rule and there's no link or no mouseover tip. (There's also an AHREF insive the DIV with the same title attribute.)

I doubt that a div "title" attribute is something that can be accessed by mobile users.  It's may only be there at that width for accessibility testing purposes.  It's odd that a browser's screen has to be less than 768 pixels wide in order for the tooltip to be accessed.

The framework that is used here seems similar to the framework for the documentation.  I definitely want to upvote any requests regarding improving the existing documentation so that it can be better used by both humans and AI LLMs.

[BKBK]

Great research, @James Moberg . Thanks for looking into this.

I hope Team Adobe will use the result to improve the user-experience.

[Michael_Willis1791]

Amen! Amen! Amen! Amen!

I use ChatGPT for CF coding.  It sucks. 

However, if you upload the CFML reference PDF using the upload tool in ChatGPT4.0, and specifically ask it to reference it when generating code, it helps - slightly.  You must ask it to use the reference the guide in almost every query because it doesn't like to retain large documents in memory, but it will do it if you insist.  It's just become part of my workflow.  But it's still nowhere near adequate.  Thanks for this post.

(note that paid user account memory is limited, so after you do this, you'll need to go into your account settings and choose some of the memory topics to delete to prevent the 100% full message, which causes it to stop remembering as you interact)

[Scott_PALADEM]

Have you tried github copilot? 

I have found it to be useful for explaining existing code. I personally am pretty untrusting of any code generators (AI or otherwise) but co pilot can save you some time writing small functions and such if you're skilled at AI prompts and give it clear specs on the code you want it to generate. It's also good at generating unit tests. The bigger the task that you give it, the worse results. And it often does things in odd ways, but it is certainly better than chat gpt which doesn't know about the most recent changes in CFML. 

no matter which AI tools you use it's very important to read every single line of code that they generate with a critical eye and do a full QA on your code changes. 

[Scott_PALADEM]

Also, it's important to understand that chat gpt doesn't have access to the internet and can't see the current CF documentation. It only has access to whatever data the developers have fed it. Adobe has no control over what version of CF documentation chatgpt is aware of.

[James Moberg]

@Scott_PALADEM That's partially true... Adobe's CF documentation isn't very bot-friendly.  I have personally experienced difficulties accessing it at times and only a blank page is returned.  The documentation version is only the "latest" version as it hasn't been consistently documented when changes in behavior, defaults or new params have been introduced.

Regarding ChatGPT, I recently added OpenAI's user agent "GPTBot" to our block list so they can't access our web applications. (I believe Cloudflare is doing the same thing by default.)

https://platform.openai.com/docs/bots
GPTBot is used to make our generative AI foundation models more useful and safe. It is used to crawl content that may be used in training our generative AI foundation models. Disallowing GPTBot indicates a site's content should not be used in training generative AI foundation models.

[Scott_PALADEM]

@James Moberg 

Interesting. Is the ChatGPT-User agent only for paid users of ChatGPT then? I have only used the free version and it specifically told me that it didn't have any ability to read urls that I had sent to it. 

[Michael_Willis1791]

mine has an attach button so i can upload files... and it absolutely can read url's when it wants to.  I've watched it do it on the screen stating something like "browing https://www.whatever.com" to give me responses.  It also also told me it can't do it, but on certain questions it does.  That's new 4.0.  Didn't see it before.

Now I'm going to give y'all something I found.

https://www.yeschat.ai/gpts-9t55kJKfKDZ-CodeFusion-Expert

It's GTP 4.0 trained on CF.  And I'm writing highly complex REST services with nested cfc's doing backflips.  The code has been perfect if you know how to ask for what you want.  Ya'll can thank me later 🙂

I just found this 2 days ago and I used MS edge to convert it to a windows app and it is now the first icon on my task bar.  I subscribed to the unlimited immediatley.  My life just got a whole lot easier.

[Michael_Willis1791]

By the way, it knows the difference in supported code between version and really loves Lucee too.  

[Scott_PALADEM]

AI is definitely a quickly evolving area. Hard to keep up with it all at the pace things are changing 🤯

[James Moberg]

Your mileage may vary depending on the complexity of the code and how well the functions are actually documented. I tested the YesChatAI app with a CFC and I questioned whether it could be optimized. The resultant code was 1) invalid (ie, toBinary requires base64 or object, not string), 2) produced the wrong results and then 3) I hit the free limit of 3 questions.

Thanks. I'll keep this bookmarked and continue to review in the future. I may even subscribe to test it out further.

[James Moberg]

I'm not entirely sure.  I know that we aren't using it, my client isn't using it and we don't know who instructed ChatGPT to scrape data from our web application.  Hopefully OpenAI doesn't allow overwriting the assigned user agent to impersonate regular browser agents.

We prefer to implement rules in the WAF instead of disclosing which spiders we block through the robots.txt file, as we’ve frequently observed it being disregarded or used to expose the areas that are off-limit.