Installation Guide: improvement suggestion

Hello Gradle community,

I am a novice user of Gradle and take this opportunity to share some suggestions for the installation documentation. For every user, there is only one first installation of a tool, so I think it is a valuable feedback to consider. To keep that as short as possible, I will focus only on the issues.

I followed the instructions from the page “Installation” Gradle | Installation but later noticed another guide titled “Installing Gradle” Installing Gradle.

Here is my experience from reading the “Installation” page.

In the first paragraph, the sentence with a link “You can download binaries and view docs for all Gradle versions from the releases page.” is misleading. So I clicked on the link, got into a new page in the same tab, and started reading the instructions on this page. I got confused; it was not the right thing to do. After a while, I went back to the initial page. I understand it makes sense to give a link to this “releases page,” but it should probably be referenced somewhere else. Actually, it is also referenced in the sections “Installing manually” (“Need to work with an older version? See the releases page.”) and “Older Releases.”

Then, for a user who just wants to install Gradle, the “Additional resources” section is not helpful at this step of the installation. It is confusing too. It should be moved to the end of the page.

The “Installing with a package manager” section is fine. However, as a Windows user, it could be interesting to explicitly say this is not applicable (if I am correct).

So finally, I really started the installation with the “Installing manually” section. Again, the link in “Step 1. Download the latest Gradle distribution” is confusing. Users should not click on it. They will end up on the “Releases” page, which is not what we want to do. The direct download links to the binary-only and complete versions are great.

The other installation documentation named “Installing Gradle” is very similar. The introduction section is good.

The same comment for the “Installing with a package manager” section: it could explicitly say this is not applicable for Windows.

In the “Installing manually” section, again, remove the link on the word “Download.” Users should not click on it. Direct download links are missing for “Binary-only” and “Complete.” It would be interesting to put the sentence: “If in doubt, choose the binary-only version and browse docs and sources online.”

That’s it for today. I hope this feedback will help you improve the users’ first steps.

Regards,
Jerome

Welcome to the community.
But as the name says, this is a community of users mainly, not a place to report bugs or make improvement suggestions, unless you want to discuss them with fellow users first.
If you want to suggest these improvements, you should open a ticket at Sign in to GitHub · GitHub.

Btw. “Installing with a package manager” is applicable to Windows if yo use one of the supported package managers, which in this case would be SDKMAN! which you could use on Windows for example using Cygwin, or using WSL, or even using Git Bash from Git for Windows.

Hi Björn,

Thanks for the reply and the tips.
I have created a GitHub issue: Installation Guide: improvement suggestion · Issue #23184 · gradle/gradle · GitHub

Jerome