[Feature][doc] Add guidelines for how to choose between java / python apis

[xintongsong]

Search before asking

• I searched in the issues and found nothing similar.

Description

Add documentation about the pros and cons of java api vs python api, and guidelines for choosing between them.

Are you willing to submit a PR?

• I'm willing to submit a PR!

[anshuman9468]

Hi @xintongsong Raised a PR for this issue. Please check it and tell if anything to add is there left.
Thank You

[xintongsong]

Hi @anshuman9468,

Thanks for your interest in Flink Agents and trying to contribute to the project. I've checked you PR, and I'm sorry to say this but it's not really what we need.

This PR is more like a general comparison of Java vs Python APIs, which is kind of verbose and unrelated to this project. What we need is a comparison of Java & Python APIs of this project, e.g., some features are only supported in Python or Java, or specific Python or Java versions, and suggestions based on that. And we are looking for something more concise, so that users can quickly identify the key information.

I'm sorry to say this after you have spent your time and efforts on this PR. In future, I'd suggest to ask in the issue before actually working on it, to check about how the issue should be addressed, and to get assigned so that other people know you are working on it and won't do redundant works.

[anshuman9468]

Hi @xintongsong , thank you for taking the time to review my PR and for the detailed feedback.

I sincerely apologize for the mismatch in expectations. I understand now that the comparison should be specific to the Java and Python APIs within Flink Agents, focusing on feature support, version differences, and actionable suggestions, rather than a general language-level comparison. That was an oversight on my part.

If possible, I’d really appreciate it if you could assign this issue to me. I’d be happy to rework the PR from scratch, align it strictly with the project’s requirements, and deliver a more concise, targeted comparison as expected.

Thank you again for your guidance and for pointing me in the right direction. I appreciate the opportunity to learn and improve.

[xintongsong]

I think drafting these guidelines takes knowledges and familiarity of the Flink Agents APIs. Since you are new to the project, I'm not sure if this is a good starting issue for you. Or maybe you can share a bit more about which differences and suggestions you plan to add, if you are working on this issue?