Hacker News Reader

Comment by zmmmmm | Hacker News Reader

What I find fascinating about Gradle is that its utterly impossible to say it lacks documentation - go to https://docs.gradle.org/current/userguide/userguide.html and see the amazing beautiful docs.

But actually learning from those docs is amazingly hard. It's like "documentation theater". If you start as a naive user coming in, it keeps teasing you that its going to teach you something but you just get abstract concept after abstract concept and you STILL don't know the mechanics of how a build works. You have to kind of reverse engineer the info that Bruce describes out of the documentation. Even when you manage to hit actual code examples with detailed explanations - they are described in a way that fails to give you the generalisable understanding of the internals that you need to actually create new things that you haven't seen before.

As a developer it generates a distinctly hostile feeling of helplessness and powerlessness.

View on HN

I love how you and others have articulated exactly how I felt. I'm not alone! There are not many tools or languages that have left me with such a memory of unlearnability. I powered through, I made things happen, but I feel less powerful in Gradle than anything else I spent so much time learning.

Gradle's documentation falls into a trap that I find many projects falling into: thinking that, if you have documented all of the thing's parts, you have documented the whole thing.

The only projects I see reliably escaping this trap are ones with commercial backing. I'm guessing the problem is that nobody does tech writing as a hobby, so, if you want to get good tech writing, you need to actually hire a tech writer.

> The only projects I see reliably escaping this trap are ones with commercial backing.

Gradle is backed by Gradle, Inc. [1] who provide commercial support and presumably a lot of development as well.

[1] https://gradle.com/

As a beginner this is how I feel about much of the official documentation and why I often search in YouTube/blogs for someone else to provide me the digested version of the docs.

None the abstract concept stuff means anything to me quite yet, and it’s what I find about the most.

It’s as if my Mac user GF asked me about how to get something done in my Windows desktop and I start with the history of Microsoft and how different is their philosophy instead of telling her “Use CTRL instead of CMD and most of your shortcuts will work the same, and file explorer is your Finder”.

Very concise description of my own experience when trying to learn Gradle from its docs, frustrating wheel spinning and utter confusing to understand from a high level to a detailed view.

This sums it up perfectly. Gradle is the best tool in the world for making me feel like I'm dumb. It is so hard to track where things are defined because the build script has something like 100 invisible imports by default. It makes for a beautiful file but a horrible experience for anyone who's new. I hate it.

Bazel is pretty similar in that respect. It has tons of documentation, and it's mostly decent prose as well... but you can read for days and get no closer to knowing how to build or fix a thing.

Random guess: they never user test new docs (especially with newbies). Docs are written by Gradle devs with years of intimate knowledge of the tool and just published somewhere in their dev cycle.

And with that, they document the things Gradle does, not how to accomplish basic tasks using Gradle.

Gradle manages to hit the same note that AWS does; lots of docs, but never the one you need.

The fact that the style and language Gradle is written in has changed doesn’t help one iota.

It's like trying to learn how to drive a car by reading the owner's manual.

Reply on news.ycombinator.com