brunch-guide
brunch-guide copied to clipboard
brunch
Add examples of conversion from other build tool(s)
This is feedback with the best intentions. Needless to say it's my opinion, ymmv.
I just read the brunch-guide for the first time and boy does this project like to pat its own back. I get it, you like brunch. It's your favourite thing in the world, which explains why you bothered to write a (otherwise great!) guide for it. But literally the entire first chapter is dedicated to emphasizing how much better brunch is than all those other crummy tools. In bold. Plus numerous remarks throughout the guide. I feel like some overly motivated sales rep is trying to sell me the brand new DishWasher3000™ which is just so much better than anything the competition has to offer and how could a smart handsome man like myself ever think that it's not? IMHO you should try to make it sound more like an objective set of instructions and a little less like a misunderstood hipster tool still trying to prove itself. Keep the benchmarks for the about page or a blog post.
I understand you want to make sure people see the advantages. Maybe they are true. You got me hooked, right now I'm trying to get the configuration running. It is much less work than various other tools although its heavy reliance on predefined structures can be a bit of a pain. My existing project isn't structured that way. I don't have an app/ directory, period. "Well you could've used brunch from the start and structured it that way, we've been around for 6 years…" Yeah, yeah, whatever.
Get to the point. Tell me how I can adjust the tool to my project, not my project to the tool. Give me an example that has a deviating setup. Your lack in market share isn't because of bad marketing, it's because you scare away anyone who already has an existing project. Nobody goes looking for a compilation tool before writing any code. And nobody just happens to write their code in the exact setup you consider ideal.
Anyway, that's my two cents, take it as you will. Otherwise this is a great guide. I wish other tools had one that is this concise and up-to-date. Thanks!
PS: #13!
How can the seventh chapter be improved in your opinion? https://github.com/brunch/brunch-guide/blob/master/content/en/chapter07-using-brunch-on-legacy-code.md
@philer just FYI, not that it makes a difference, but the guide was contributed by a user, not directly by the authors/maintainers of Brunch. It was originally written in French as a blog post, then translated and put in its current format. The tone remains heavily that of the original author's.
I agree that the hyperbole and personality in it could be dialed back some, but on the other hand making it strictly dry and boring might not be so great either.
Not trying to make excuses, just offering some context. The feedback is appreciated, and any contribution you could offer to improve upon it is welcome.
I found the original post in french. It's a good guide and it was translated pretty closely.
The difference is, it's "some guy's blog post", rather than "the official guide". I'm just saying that making it sound a little more objective might be a good idea. As a random passer-by I don't particularly care where the text came from, my first impression was just "wow, these guys really want me to like their project".
As for examples I can't be too specific because I'm still figuring things out myself. Here are a few questions I asked myself while setting things up:
- How can I get rid of the extra require + init line in my .html file? I want my core module to run automatically.
- One or two examples that don't follow the default directory tree. At first I wasn't quite sure how much of it is obligatory and how much I could adjust. The config documentation was very helpful in that regard, however it is quite brief and required some trial and error.
- How can I wrap the whole thing in an IIFE and pass in globals? Traditionally my modules were wrapped like this:
(function(win, $, undefined) {
// do things
}(window, jQuery);
- I'll also be curious how to use entry points once the feature has landed. :D
How can I get rid of the extra require + init line in my .html file? I want my core module to run automatically.
I guess this is something that entry points could handle, (but could be slightly messy with the code splitting), but I wouldn't do it with them just yet, and let them stabilize/gain user feedback first.
If you want to get rid of that line, you could create a vendor file that just did require('init') and make sure it always got concatenated last (by using config.files.javascripts.after)
@es128 autoRequire is pretty much what I was looking for. I don't think it's mentioned in the guide though. Of course the guide doesn't have to cover every single available option (although that would be nice) but this one seems pretty basic to me. None of the other bundlers I've tried require that extra line.
I think the option was added after the guide was written, so definitely PR welcome to amend for that.