feedback on the readme & process

[sole]

I was going to write an email but I thought it would be better to put it here so it's public and documented & shareable for the future.

I am following the steps to install and try this out, and I can't stop thinking WHY DO I NEED TO DO ALL THIS all the time. I think if there was an explanation somewhere in the README as to what the structure of the component is and what components/polyfills do we rely on and why, it would be SO MUCH easier to grasp why bower or gulp have to be run.

We're basically missing content--right now it's too sparse! I would:

• add a longer explanation of what this is right under "A Brick custom element starter-kit.". Something like "this is the bare minimum you need to build your own Brick-style elements. It includes a demonstrative custom element with some basic CSS styling and a gulp script to help you package and build the component ready for distribution".
• add a code walkthrough. what goes where and how do I use this? I would like to know that I have to look at src and do things there, and at some point run some script that does some other things
• add some "hello world" content to the custom component because when I try to test this out I am not sure it works at all, since it's just a big mass of nothingness.
• can this work to package dependencies that your component might rely on? a bit like that polymer tool we mentioned to grab all html imports stuff into a single file? if it's the case I would highlight this with an example + mention that so it's obvious. If it's not I would make it the case and also say this is entirely optional and depends on your particular case.

Finally... why a local server? why why why? I just want to open an index.html page, why can't I just do that? In fact I just did that and I'm not sure if it's opening what is supposed to be opened. Where do the things that gulp build builds go? I can't see any build folder. I am very confused at this point. You don't want to confuse people. (I should make this into a t-shirt)

that's it for now, hope it helps!

[potch]

All good feedback! The tl;dr is this is most definitely a work in progress, so please assume good intent and give the benefit of the doubt when things aren't quite there yet :)

The big thing to understand about this project is it is not a tutorial. It's a boilerplate. If you want to grab something to start with and get off running quickly and you know what a web component is, this is for you. We can give a bit more documentation around the project structure, but most of what is here is very much so the common case for frontend github projects: package metadata at the root, primary files in src, a (as of yet unmade) dist and test directory for compiled files and tests respectively.

As for Gulp & Bower, a command-line build tool for things like linting/testing is fairly common at this point. We should explain that we are using them, but this project's goal is not to convince people that it's a good idea.

The reason we have the server task is because some things (and it's hard to know ahead of time which depending on the browser) just don't work when done over file:/// protocols. Think things like webfonts, etc. Additionally, gulp server starts a watch process, which means the workflow (make a change, compile stylus, run tests) all happens automatically whenever you save.

We should definitely have a hello world innerHTML thing in there, so there's no question whether it works.

We have a gulp-vulcanize plugin we are pulling in to do minification across HTML imports, but really the vulcanization shouldn't be done at the component level, it should be done at the project level (projects using the components via HTML Imports). If you vulcanize at this point, ever component has a copy of platform.js minified inside, which is definitely not the right thing.

I hope this clarifies the confusion somewhat!

[dotch]

thanks for the feedback sole!

going forward we should definitely clarify the readme as to what this boilerplate is for and what is included.

adding a dist folder where everything is compiled to is also up for discussion.

the local server is needed even in the most basic version of a component because chrome will not allow you to do html-imports via file:/// (with and without polyfill)

also this is not trying to be a minimal boilerplate for a vanilla webcomponent, instead it will be brick specific and therefore containing opinionated complexity like bower, gulp, stylus(or less) and brick-common files.