4 ms·
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.ht
by zmmmmm 6y ago
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 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.
- piva00 6y agoVery 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.
- oblio 6y agoRandom 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.
- cratermoon 6y agoAnd with that, they document the things Gradle does, not how to accomplish basic tasks using Gradle.
- Noumenon72 6y agoI 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.
- lajun 6y agoThis 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.
- ashtonkem 6y agoGradle 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.
- deleted 6y ago[deleted]
- Groxx 6y agoBazel 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.
- mumblemumble 6y agoGradle'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.
- tn1 6y ago> 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/ https://gradle.com/
- cratermoon 6y agoIt's like trying to learn how to drive a car by reading the owner's manual.
- culopatin 6y agoAs 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”.