Not to say there's anything wrong with tutorial-style documentation in and of itself. However, it becomes problematic when it is the only documentation.
Then you just find yourself digging around in source code because the "It's easy, simple and magic!" style of documentation turned out to be woefully inadequate, if not actively confusing.
I guess one reason is that the tooling is there to bring in the magic in the first place.
The other could be that tools being created because of the needs of a specific workflow and the magic is there because authors just wanted to have something working, then it got popular and now people want to use it in all sorts of workflows.
The thing about magic is it's just as mystical when it breaks as it is when it works. That's why it's magic.
That's the most concise way of describing the problem I've seen yet. I'm stealing that. Thank you!
Hibernate went through this too. I came to prefer myBatis, but going through JPA is nicer. JPA is certainly not less magical than Hibernate though, just the culmination of many years of work in this area.
SQL Alchemy is also nice like this. The magical ORM is built on an extremely robust and well-documented relational database querying library. There's an escape hatch to reality if the magic fails you, always. Can't say that about Hibernate 3—see the HQL/Criteria API madness (again, fixed in JPA).
I went through a very hyper-annotation period with Java. I have since calmed down. I still make annotations, occasionally, but I don't let them be the only route to the work. Always have the annotations help something build a configuration through a standard API, then the work happens against that configuration. You can ditch the annotations if they're a pain that way, or bridge between something else (XML probably) without writing the same code twice.
Speaking of magic or trying to be too clever with your code reminds me of the Grep Test [0], which I always try to conform. In the end it's not fun forcing others to deal with your magic. Remember: code is read way more often than it is written, so don't be lazy to type a bit more — help others.
I always felt indifferent about it, and the config style felt a bit like Revenge of Grunt, but after using it and especially after reading your tweets and responses to issues on github, I finally understood why Webpack is so popular.
I know project maintainers often work hard for little reward, but you're consistently gentle and helpful with beginners and people with complaints about Webpack. Thank you.
This goes to more than just you, but please always feel welcome to reach out.
Mostly due to less magic, tbh
I learned how to use Webpack but still think it sucks and it's incredibly complicated for what it does for 90% of use cases.
Smart defaults. -Then- let me configure if I need to.
"Can we make smarter defaults"
We support a lot of build targets and are agnostic to library and stack so it's going to be a challenge but with your help and the community I know we can get it done.
webpack-make --scss --hot-middleware --blah
or something, potentially?
Since the core team needs to focus on implementing more opt features like rollup and better top level minification, we left this for a chunk of our contribute team to help design and come up with. Help always wanted!!!
but also please have those discoverable.
I've come to hate the word default because people have a different idea of what it means.
Is it a site default, an app default, per-instance default ...?
Which one applies? Apps should document at runtime what the values are and where they come from.
However I think that if you have a clear model of how everything works you don't need that much magic because building the solution to any particular use case is not really an onerous task in itself.
I would infinitely prefer to use JS tooling over Java's in general so maybe that's not saying much.
Webpack is practically a blank slate.
That's good. It's kinda funny how this is a very frequent pattern: Build something full of magic and, as you grow more mature and hit pain points, end up removing the magic.
I've had a very similar experience in my career so far as a dev. My code used to be full of magic, auto-guessing things based on how methods are named, etc. I've moved away from that, it wastes more time than it saves.
Anyone else with the same experience?