[GitHub] [arrow-adbc] aiguofer commented on a diff in pull request #724: docs: add docs for Python Flight SQL Driver, add link to Go Snowflake driver

["aiguofer (via GitHub)" <gi...@apache.org>]

aiguofer commented on code in PR #724:
URL: https://github.com/apache/arrow-adbc/pull/724#discussion_r1214619448


##########
docs/source/python/flight_sql.rst:
##########


Review Comment:
   I thought about this, but as a user looking for information on how to use the Python bindings, you wouldn't think of clicking on the Go section. While I was trying to figure out how to use this I struggled to find consistency on what's in the Go page vs what's in the C/C++/Python page.
   
   The current organization might make more sense for people who are deep in the project and understand the relationships between the various language implementations. However, IMO the docs should be tailored to potential users looking to use ADBC in their preferred language. I started thinking about reorganizing all of this but didn't want to make my PR too invasive. I feel like an organization like the following would be really helpful for users:
   
   * Language (one per language)
       * ADBC Manager description (what is it, how does it work
       * Usage Example (code of how to query, fetch results, look up metadata, etc)
           * If multiple APIs are available (like dbapi for python), brief description and explanation of each... or simply using the "tabs" for code blocks showing how to do it with each api
       * Driver (one per available driver)
           * How to install
           * Example code to use
           * Available DB, connection, and statement options (this could be a link to the underlying implementation driver, or the API for the language if it has some enum/dataclass/struct describing the options in code)
   
   Under an organization like ^, the current `Python quickstart` could just be moved to the Python section for `Usage Example`



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org