search

fernandes / arara

A material design theme for Ruby on Rails 🦜
MIT License
12 stars 1 forks source link

more documentation, please! #2

Closed leastbad closed 4 years ago

leastbad commented 4 years ago

I know that it's probably early days but the almost complete lack of documentation is daunting. eg depending on where I look, you describes it as both a gem and an npm package

This project feels exciting but it would triple its approachability if it had:

A lot of really amazing OSS projects omit similar things, and it hurts them. Basically, someone has to go hunting for answers and just have faith that the result is totally worth it.

Basically: help me fall in love!

leastbad commented 4 years ago

For what it's worth, I have:

rails new arara bundle add arara yarn add arara added mount Arara::Engine => "/arara" to config/routes.rb bin/webpack-dev-server rails s

And this is where I'm stuck. I see no routes for the engine when I rake routes. There's so much here I want to play with, but it's not obvious at all what I should be doing to make this work.

fernandes commented 4 years ago

hello @leastbad , thank you for your message

a declaration of vision and intent eg. who is this for, what makes it special, what does it compare to, what assumptions does it make

Actually this is something I created to use in another project and thought would be nice to open the source and share it with other people 😉 (TBH I'm surprised you opened this issue, for a few seconds I thought was a bot hahaha)

I have no intention on making this the next big thing™, if you want to collaborate adding more documentation or opening any PR, I'm more than happy on helping you

My first step will make the developer instruction better, so at least you can open the project locally and see the demo pages (and be more confident on using it)

I also want to deploy it to some page, so people can see it before digging into the weeds

thank you again! 🙇

leastbad commented 4 years ago

Right on. Well, I'm very likely to make some contributions but as I said, I currently have not succeeded in actually getting it to mount. I can't wait to see what you've done!

fernandes commented 4 years ago

hello @leastbad

I made it easier to run the project, can you please follow the instructions under the demo section on readme

I tried 2 times locally, it worked, hope you can see the demo and play with it a little bit, have fun! 😄

fernandes commented 4 years ago

hey @leastbad if you have any other question about it, please let me know! thank you!

leastbad commented 4 years ago

Hey Celso! Thanks so much for tightening up the install process. I have it up and running now. It's really interesting to go through and see how you decided to implement certain things.

You mention in the project README that you were inspired by ActionCable but it actually doesn't seem like you use it in this theme!

I am definitely new to Rails engines; I use Devise but conceptually, it's not obvious why the project seems to live in test/dummy. Is that a convention of some sort?

I guess my question is if someone wanted to use Arara in their project, what would you imagine they do to integrate with what you've done? As a proof of concept it's really interesting but generally step one of integrating any random theme is to take the raw HTML from the example pages and mess with it until I feel confident I understand what's happening.

I cannot speak for everyone, but my hunch is that people decide what theme to purchase by how it looks - color, typography etc - but it's the sample pages that they are really paying for. I know it's true for me... giving me a style sheet and some example widgets gets me a blank screen but if you say "this is an ecommerce theme" and it has sample pages for all parts of the process... it's that HTML structure that is now providing most of the value.

I'm excited by ViewComponent for this reason, because it lends itself to this kind of composition. However, the tech only gets us about 75% of the way there. It's those constructed pages that are gold.

I'm going to keep going through this, but so far I'm impressed. Did you write the Stimulus controllers yourself, or did they come from somewhere?

leastbad commented 4 years ago

Oh, the one thing I wanted to ask was if the menu widget would eventually support nesting?

fernandes commented 4 years ago

This is my first NPM package, the build system was inspired on ActionCable and Material-UI

the JS package build system is inspired in the ActionCable one, if you click on the link, it'll take you to the package.json there

I am definitely new to Rails engines; I use Devise but conceptually, it's not obvious why the project seems to live in test/dummy. Is that a convention of some sort?

yes, this is a rails convention, it's where your test directory lives, so you can write the tests simulating a rails application using the engine

I guess my question is if someone wanted to use Arara in their project, what would you imagine they do to integrate with what you've done?

I don't understand your question, you mean what should the do to use Arara into their project? You just need to install the gem, npm package as use it, like it's working in the test/dummy

people decide what theme to purchase by how it looks - color, typography etc - but it's the sample pages that they are really paying for

it's not a theme, it's some components based on a design system (material design)

components < design system < theme

the tech only gets us about 75% of the way there. It's those constructed pages that are gold.

Awesome, now you only have 25% of the work left, good deal no?! 😉

but so far I'm impressed

thank you 🙇

Did you write the Stimulus controllers yourself, or did they come from somewhere?

by myself

leastbad commented 4 years ago

Hey again, I shouldn't Github when tired. :)

I spent a lot more time with the engine today and I'm caught up - thanks for all of your clarifications. I guess when I was asking about how to use it in a project, I meant literally - add the gem, add the package, and then start rendering components. I'm going to give it a go.

I also had a proper opportunity to look deeper into the Stimulus controllers and I see what's up. While it's true that you wrote them, they are thin (in most cases) wrappers on an existing library. There's nothing wrong with this - Stimulus is amazing for wrapping other components.

It didn't seem from my high level pass that any of them had disconnect() events... I assume everything plays nicely with Turbolinks out of the box?

Final question for now, I promise (and I appreciate your patience so far). I believe that the Stimulus controllers you created have value as a set of standalone controllers that can be registered. My friends and I have started to aggressively publish stimulus controllers to npm, I've released stimulus-image-grid and jquery-events-to-dom-events so far, and I have 4-5 more coming soon. Would you consider publishing a separate npm package that depends on the MDC package and just exposes your Stimulus controllers?

If that's not your idea of fun, would you be interested in me doing it, while giving full attribution? Our goal is to make sure that there's an impressive and growing number of composable stimulus controllers in the wild, and I'd love to see your MDC wrappers among them. Sure, people can pull them out of arara, but that's not ideal, logistically.

BTW, there's a lot of Stimulus folks hanging out in the StimulusReflex Discord. Please consider yourself invited: https://discord.gg/XveN625

fernandes commented 4 years ago

they are thin (in most cases) wrappers on an existing library

exactly, the mdc one

everything plays nicely with Turbolinks out of the box?

yes

about stimulus controllers, I have zero intention on doing what you proposed, if you wanna create a npm package, go for it, don't even need the attribution 😉

thanks for the discord link