Description
Our single-page installation guide can be overwhelming for new users since it has too much information. It would be nice if we can better organize this information.
Improvements
Currently our installation guide is not properly organized.
- It should separate out the installation for various operating system and distributions.
- It should separate the installation methods based on production-grade installation vs quick-installation.
- Wherever, bash commands are presented, it should present them with proper comments about what those sets of command do. It shouldn't do bash variable assignment but provide simple commands to execute.
Suggestions
Suggestion for 1:
PostgreSQL Installation Page does it great job here:
- User can select the operating system,
- Once the OS is selected, it gives the option to select the distribution.
Based on it, it redirects the user to different web page.
We should have something like this. It's sad that we do our builds for so many operating systems and architectures but we fail to present them properly in our documentation.
Suggestion for 2:
Our installation guide currently has curl https://clickhouse.com/ | sh command in the very first. Even though it is a great quick way of installation, most of the internet don't like it. There are countless blogs specifying the downsides of it. I think a new user can consider it bit negative. IMO, we should present the distribution specific standard installation method at the top.
Suggestion for 3:
Currently we present a set of long commands with zero context about why one needs to run them.
At the same time, PostgreSQL present same information with much better context
