search

confluentinc / ksql

The database purpose-built for stream processing applications.
https://ksqldb.io
Other
128 stars 1.04k forks source link

Mixed content regarding ksqlDB CLI on docs #7130

Open guozhangwang opened 3 years ago

guozhangwang commented 3 years ago

When trying to use the ksqlDB CLI to do manual auth testing, I found the doc information are quite inconsistent across:

Specifically, the docs seem sometimes assuming the CLI were downloaded from CP, and sometimes assuming it is from docker compose. I admit I was not very familiar on ksqlDB CLI, but still I feel the current docs are not very helpful for someone like myself navigating through the woods, and I actually share a lot of the confusing experience with this SO:

https://stackoverflow.com/questions/64808128/how-do-i-install-just-the-ksqldb-cli-tool-on-linux

I think we should try to clarify better in those docs which ksqlDB CLI should someone get, and cross-reference each other that under different installation environment you'd expect to locate / run your CLI differently.

agavra commented 3 years ago

@guozhangwang - looking through this I see two ways:

  1. the confluent local installation
  2. the docker installation

The docs are pretty consistent in the sense that all the CP docs reference the first method and all the open source docs reference the second method. The last CLI link you reference (confluent cloud CLI) is another thing entirely - it is used to manage the control plane for you cloud cluster and has nothing to do with ksqlDB directly.

I tried making some changes in the docs, but couldn't come up with a way that is clearer than what's there today.

@JimGalasyn any thoughts?

JimGalasyn commented 3 years ago

@agavra The docs around installation are quite broken, but now that we have proper rpm/deb packages, we can definitely fix them. (What's surprising and a bit dismaying is that we haven't had any customer complaints about them!) @colinhicks and I have chatted a bit about this -- once we get CP 6.2 shipped, I'll have some bandwidth to rework this content.

agavra commented 3 years ago

@JimGalasyn thanks! I'm still a little confused though:

but now that we have proper rpm/deb packages

Didn't we always have these available for CP releases? Are you referring specifically to some docs in the ksqlDB microsite?

guozhangwang commented 3 years ago

@agavra I agree with most of your points here, but for the last link https://docs.confluent.io/platform/current/ksqldb/installing.html what I was originally confused is that we have a paragraph under Docker support telling you can deploy ksqlDB via docker, and then later we talked about installing ksqlDB locally. Now that I understand the installation path better, I'd suggest we just remove that Docker support section all together, or maybe add that within the installation section, emphasizing that "alternatively, one can also deploy...".

WDYT?

agavra commented 3 years ago

Thanks for the thoughts @guozhangwang - makes sense to remove the Docker Support in that paragraph, especially now that we have proper tarball support.