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.
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.