Hi! I would like to report again that the docs are barely unusable as they are. There are tons of things in the docs, but no-one can discover them. As an example, if you search for doco in google, it is likely it will return a URL like "https://docs.gradle.org/7.4.2/userguide/userguide.html". If you open that page, it doesn't have a search box. For the search box to be visible, you have to use "https://docs.gradle.org/current/userguide/userguide.html". And because the link to the single page manual is hidden, you basically are doomed (https://docs.gradle.org/7.4.2/userguide/userguide_single.html). I think most of the complaints about Gradle docs would go away if it defaulted to the single page docs. At least one can rely on CTRL+F to figure out information.

+1, I rarely search inside Gradle docs, I always go to Google to use it as search engine for Gradle docs, except when I am checking the javadoc, but here I get a search bar

At least one can rely on CTRL+F to figure out information.

Unfortunately not. 😞 The "single-sided" docs are just an excerpt. Most probably because they are just not wired correctly and no validation present, but noone cares to improve it it seems: https://github.com/gradle/gradle/issues/16760 And also https://github.com/gradle/gradle/issues/15867 :-( I wasn't aware that on version-specifc docs you have no search bar, but only on the "current" one. :-(

it's really a bummer to have so much doco and that no one can find them

Well, that's a bit overstated, as Google could find the right page, and you can use the "current" version with search bar, and the one-page version for most things with Ctrl+F. But there is definitely a significant improvement potential.

google is just so much noise

Same here, unless Ctrl+F refuses to find it, I struggle to find the correct search term and then at some point remember that it is just an excerpt and use the built-in search 😄

plus I don't use google most of the time. Privacy matters, I use Qwant, but that's another issue 😄

DuckDuckGo can find Gradle docs too without privacy issues. 😉

Just search in the source tree with IntelliJ or

grep

=> no privacy issues at all 😄

I would like to point out https://boards.greenhouse.io/gradle/jobs/3694977

It's not so much about the content @Amanda. It's about single- and multi-page have different style, single- and multi-page have different content, search is only available with

.../current/...

, not even with

.../<current version>/...

, ...

👍 and a few other things on the list for the TW once we have one. I agree the content is great!

Well, the doc writers we have at work would not be able to care about these points, at most complain and let some developer fix it. :-D

Another issue with search via google is that it prioritizes older page and sometimes when you try to switch to current you just get 404 since layout changed or some part of the docs was removed/merged

I'd say potential for another feature request to keep old links running by redirects to appropriate replacements. Not sure how well that is possible though. :-D

It's common issue for a lot of projects and I haven't seen good solution yet ,(

Doesn't mean Gradle people couldn't come up with something 🙂

+1, I rarely search inside Gradle docs, I always go to Google to use it as search engine for Gradle docs, except when I am checking the javadoc, but here I get a search bar

Fwiw, I never use Google to search the Gradle docs, I always go to https://docs.gradle.org and use the search box there. That being said, I rarely, if ever, use Google to search anything about Gradle; but I'm ready to admit I'm not a lambda user.

Search engines can be instructed with metadata to prioritize the latest version. But, this requires rewriting of the old docs and knowing where they should point to now.

@melix I had the same surprise recently, the search box is only available on the

current

documentation. It has to do with the search framework not properly handling multi-version or something along those lines. I can see that both are confusing (searching older doc with the implicit hope of finding a newer concept/API vs not being able to see the search box on older version).

That is a good idea!

Note that in my case it was the latest, only referenced via an explicit number instead of

current

. But it doesn't change my mind: there should be a single page, searchable with CTRL+F.

I don't like custom control F tbh, prefer a search box

the search box only exists because there's no way you can find anything in the docs today. I'm fine with a search box, but if the page is a single page, collapsed as in the spring docs, you don't need a dynamic search, you can have a static one.

I actually prefer both like it is now, just with the single-page doc fixed regarding the missing chapters and programmatically ensured all are there. If I send someone a link, I usually prefer the search result from the search box instead of the single page result, as those single pages load faster and also sometimes browsers do not cleanly scroll to the given anchor. So usually if I find the information I want to link to on the single-page Gradle docs, I search it there with Ctrl+F, then I search for it in the search box to get the split-docs link I want to share.

the search box is terrible. Since it lists a few entries only, you can't even find docs which exist, because a term you search might be too frequent. I just cannot imagine how anyone can think the current situation is acceptable.

Spring also provides both, single and separate pages.

yes

Which is a bug, that I reported and linked above. 🙂 Let's hope the new doc engineer Gradle hired will improve on all of that. Let's give him some time to land and come up with an amazing solution.

@melix sorry it is just a personal preference, if I control F, I want to get the browser search box, both, desktop and mobile, and there are webs which doesn't allow that easily like some framework for forums (maybe Sonarqube forum? I don't remember), and every time I have to go to the three dots to be able to open the browser search bar which is a pain in the ass... For me is like, I am using IntelliJ and I press control F and I see some UI component, if it was possible that another project overrides it to have a totally different UI component with different UX, and having to go manually to populate the original UI component... probably world burns out.

@Javi I don't think anyone suggested intercepting Ctrl+F, quite the contrary actually!

I misunderstood then, sorry 😞

saving thread to help doc eng with ideas with they start 😉

Hey everyone! I'm the docs engineer amanda promised a few weeks back. I see a lot of valid complaints and great ideas in this thread, and I will fix this issue ASAP (give me a few days to onboard though!). If anyone here has other feedback or docs ideas they'd like to discuss with me, please reach out via DM -- I'd love to hear your ideas. Thanks for caring enough about the docs to discuss them here -- I know they aren't perfect right now, but hopefully with help from y'all I can get things moving in the right direction.

Hey @nate 😊 I have one that I think wasn’t mentioned yet. It’s hard to get implemented across the board, but if done right it’s awesome for the UX. Hackable URLs, currently it is impossible to change the version in a URL and get to the same docs of the other version. Similarly,

current

links often end up in a dead-end, because nothing was implemented to forward them to their new place.