yeoman / yeoman

Yeoman - a set of tools for automating development workflow
http://yeoman.io
10.08k stars 735 forks source link

Refresh yeoman.io in 2014 #1245

Closed addyosmani closed 10 years ago

addyosmani commented 10 years ago

It's been over a year since we first started working on Yeoman and in that time, the site hasn't really had much of a refresh, beyond docs/release update. I feel we have an opportunity to offer a lot more value to new users landing there :star:

Some ideas:

Note: I'm intentionally posting this on this repo rather than yeoman.io to ensure we have maximum community visibility on discussions about the site :)

addyosmani commented 10 years ago

Btw, if anyone has other ideas for how we could improve, we're excited to hear em!

excited-adventure-time gif pagespeed ce 7iurnff2ra

sindresorhus commented 10 years ago

Agree to everything

ztpkhai

Joe8Bit commented 10 years ago

The who's using could be a big win, I could organise half a dozen or so very large banks and financial institutions to list of who's using Yeoman, and it could really help in accelerating adoption at others. I'll check out the yeoman.io repo and add send a pull when needed.

Plou commented 10 years ago

A section to highlight some of the greatest generator could be nice. I think about a short sum up of what it can do and some learning resources (Jekyll, reveal and some MEAN generators).

pankajparashar-zz commented 10 years ago

+1 to all the points.

When I first started using Yeoman (specifically the generator-webapp), I actually struggled a lot to make it work. I understand that the team has a done a lot of work in documenting the steps to install yeoman and its generators, but most of the time it simply doesn't work!

Hence, I feel the need to massively improve the docs and cover important aspects like,

As @addyosmani said, the website needs an overhaul to highlight the important dimensions of the product. Also you could add a list of generators (recommended by the yeoman team), just like we have it for Grunt.js (grunt-contrib plugins) so that first time users can safely rely on using them to build their website.

addyosmani commented 10 years ago

@Joe8Bit that would be fantastic. We'd really appreciate it!

@Plou Definitely! This is something that @sindresorhus currently does with the Bower registry search page and we could easily curate and up-to-date list of featured generators.

@pankajparashar +1. Common errors are currently something we've documented half a dozen times in threads on the issue tracker but this info could be properly aggregated and summarized in one place. We can work on that.

One piece of feedback we keep hearing from Windows users is that our generators seem to work a lot more smoothly on Mac/Linux (because of how we resolve deps) but they tend to need to manually install things like Compass or Phantom when things fall over more often. We should properly document how to workaround these issues to save them time.

coffeeaddict commented 10 years ago

As a newbie (to yeoman, not web-dev) I found the site very clear. I would not stress the 'above the fold' thing, unless you get heaps and heaps of complaints about that. (If it aint broken, dont fix it)

WMeldon commented 10 years ago

I'd love to see better documentation on generated boilerplates. I started with the Ember generator before I really knew Grunt, so figuring out anything was brutal.

I great example is require('load-grunt-tasks')(grunt);. I finally understand it (and it's a great tool) but that opacity can be frustrating to someone getting started. A link to load-grunt-tasks and maybe a brief explanation would have done wonders for me starting out.

In addition to better surfacing the generators, I'd love to see some community clean up of them. Better docs and commented code. A lot of what Yeoman puts out looks like black magic because it's so advanced. But I think that with more and better explanations on what was made and why it was done like that, it can be an extremely powerful tool for educating people on modern Front-End development.

The .htaccess file on HTML5 Boilerplate is probably my favorite example of what I'm talking about. Anyway, just my thoughts after a few months of revamping my workflow.

tomlane commented 10 years ago

waiting

If I can find the time, will be happy to help. \o/

patelnarendrab commented 10 years ago

@addyosmani : +1: Same here. Hope I will help, if have time.. :)

gazzu commented 10 years ago

thanks for the amazing work!!!

gavriguy commented 10 years ago

Add some virtual freebees - stickers, badge (like the new built with grunt badge) etc.

danielchatfield commented 10 years ago

Is there somewhere I can order some real stickers? ᐧ

On 18 December 2013 17:28, Gavri (Gabriel) Guy notifications@github.comwrote:

Add some virtual freebees - stickers, badge (like the new built with grunt badge) etc.

— Reply to this email directly or view it on GitHubhttps://github.com/yeoman/yeoman/issues/1245#issuecomment-30861939 .

For contact info visit: www.danielchatfield.com

elsigh commented 10 years ago

I'm late to the game, but giving a talk next year on taking a webapp to mobile with Phonegap - and so I thought I'd check out yeoman last night - I'd love to show folks a canonical way to do things versus giving them a personalized gruntfile or something.

I'm pretty n00b, but when I ran sudo npm -g install yo it took for freakin ever and makes a ton of network requests. I sort of felt like it as installing an entire OS and that I would never be able to get a classroom of students through that step alone.

Then I had to get the generator install commands right (as simple as it is you'd think that would've taken no time) - but it made me wonder if there's any way to package up one zip or dmg that has everything and that just works (ok, I know that's also really hard). That's crazy-broad feedback, and probably as much about npm as yeoman, but I figured I'd share it anyhow. In particular I guess I'm slightly off from the typical use pattern as I tend to prefer writing my server handlers in python over node.

Also, with my web app I wanted to use zepto+backbone instead of jquery and didn't see a way to do so - I just saw that I got "jQuery" out of the box. Again, maybe I'm doin it wrong. And what's the difference between a backbone app and a webapp anyway? Conceptually I don't know - I could install both generators and check them out and maybe get it. Again, just sharing some first impressions!

robwierzbowski commented 10 years ago

I'd be happy to wrap the site in generator-jekyllrb, and help out with coding where I can.

lid2l

mayhemds commented 10 years ago

How about creating a one click install and a user interface.

SBoudrias commented 10 years ago

@danielchatfield There's sticker on RedBubble - but I don't know who get profit for these sells.

@elsigh The installation output is pretty classic NPM. It always prompt a bunch of output which can look scary, but really it's just output. You can always run it with the -q flag to limit the quantity of output.

Sure if you need to setup Node, NPM, Git, etc, it may looks like a big install. But, Node.js is used thoroughly with Yo, Grunt and Bower - so it really makes no sense to get a standalone install for Yeoman. It is a tool based on Node.js and its ecosystem.

Note that most of the install process can be simplified using homebrew if you're on Mac. On windows well, like everything on windows, it takes time.

@mayhemds There's already a user interface (yo on the command line). And there's work to bring Yeoman on a GUI on editors like Bracket and WebStorm. About one-click install, look my answer just on top.

tomlane commented 10 years ago

Red bubble have Yeoman stickers I believe. Not sure if they're official though. On 18 Dec 2013 17:56, "Daniel Chatfield" notifications@github.com wrote:

Is there somewhere I can order some real stickers? ᐧ

On 18 December 2013 17:28, Gavri (Gabriel) Guy notifications@github.comwrote:

Add some virtual freebees - stickers, badge (like the new built with grunt badge) etc.

— Reply to this email directly or view it on GitHub< https://github.com/yeoman/yeoman/issues/1245#issuecomment-30861939> .

For contact info visit: www.danielchatfield.com

— Reply to this email directly or view it on GitHubhttps://github.com/yeoman/yeoman/issues/1245#issuecomment-30864390 .

elsigh commented 10 years ago

@SBoudrias I had Node, NPM and git already installed fwiw. I actually already had homebrew installed on my mac but I just followed the directions on the page - as most everyone else would probably do. So maybe a link to "Install w/ Homebrew" would be cool. Otherwise, I prefer @mayhemds audacious idea. =)

mayhemds commented 10 years ago

@SBoudrias The command line is ok if you know how to use the terminal, but for people moving into the world of web/dev it can be quite daunting. Also I can't see a lot of design agencies allowing there staff to use the terminal. ( Mayhem comes to mind! ) Just a thought.

SBoudrias commented 10 years ago

Also I can't see a lot of design agencies allowing there staff to use the terminal. ( Mayhem comes to mind! ) Just a thought.

Why would an agency control the tools their developers use? (I work myself in an ad/design agency and I really can't relate to your experience - cmd is installed by default everywhere and ITs can't disable it)

Bretto commented 10 years ago

+1 for MEAN generators

mayhemds commented 10 years ago

@SBoudrias I think you would be surprised. There a lot agencies that want you to conform to their way. Don't use X but use Y. I worked for one agency and everything was locked down and you needed permission from IT Systems to gain access to area's on the Mac. Noted I left quickly but there are some around.

sindresorhus commented 10 years ago

I'm pretty n00b, but when I ran sudo npm -g install yo it took for freakin ever and makes a ton of network requests. I sort of felt like it as installing an entire OS and that I would never be able to get a classroom of students through that step alone.

Yeah, npm is way too noisy, but keep in mind that you only install yo once, so i don't see how it matters that much, and when you install yo also get grunt and bower, which is actually the biggest part of the install. The reason there's a lot to install is how npm works. It uses nested dependencies, which means both yo and a dependency of yo can depend on different versions the same lib. This amazingly powerful at the little cost of a bit more things to install. But it results in way more reusability and less NIH, which can translate into better quality.

"Install w/ Homebrew"

The Homebrew dist of Node is broken, as it changes where global node modules are installed to a directory not in your path, so CLI interfaces doesn't work automatically. We strongly suggest anyone to install directly from nodejs.org using their installer package.

hemanth commented 10 years ago

Count me in!

me

donaldpipowitch commented 10 years ago

@WMeldon Good points. It is quite difficult to find out why something is done in a specific - no matter if it Yeoman or a different project. But Yeoman could definitely improve on this.

Maybe this is a different topic, but I have to say that Yeoman - and I mean Yo with this and not Bower or Grunt (I always disliked this naming convention) - is one of the new shiny web tools I don't get. Maybe I do this wrong, but every generator does something which I don't like/want/need and reverting or customizing this takes more time than doing it without a generator in the first place. Maybe it would be great, if you could spend a little time on a more unobtrusive way of generating code. Maybe something like a yeoman / generator-simple-webapp or something like that which just makes minor changes instead of big ones. I would also like to use generators in a more dynamic way: save configurations like template engine, swap out sub-generators between generators, make small modifications on top of existing generators... Of course I could fork a generator and could create my own, but it seems that Yeoman would favor generic generators instead of more custom generators. If I get this wrong, I would encourage you to do less work on maintaing generic generators and help people creating more custom and individual generators with better docs or smaller components which can be sticked together.

pahlers commented 10 years ago

I think the site is great, but it has a lot of information at ones. It shocks a newbie and the advanced user can't find the right information fast enough. I like the information layering of http://angularjs.org/ and http://gruntjs.com/.

First contact Angular has a main topic 'Learn' with a lot of information about how to start. Grunt has the topic 'Getting started.

Feeling better Angular has under 'Develop' a topic 'Developer guide' with an explanation about the structure and the concepts of Angular. Grunt has a topic Documentation/Advanced'.

Deep in the rabbit hole Both sites has an API reference.

and deeper Both projects has a lot of documentation in the code it self. Just look into the code to understand what's happening under the hood is great.

addyosmani commented 10 years ago

For those with feedback on Yeoman or generators, I've created #1246 for us to track your comments there. We really appreciate your input and look forward to hearing more. Please note that this thread is just for comments related to the site and keeping these topics separate helps us track what we would like to improve. Thanks!

addyosmani commented 10 years ago

@WMeldon 100% agree that our generators need better documentation. I'm wondering if for tips users find in our Gruntfiles whether it's worth having say.. a docco style documentation/code side-by-side view so that we can easily link up to tasks we're using or explanations for why something is being done.

@tomlane that would be amazing. Are you interested in helping out with mock-ups or an implementation?

@mayhemds for developers without access to the terminal, I generally recommend tools like CodeKit, Prepros, Hammer and so on as they provide a decent beginner - intermediate set of tools for iteration workflow. For anything more serious I think an agency would find value in enabling terminal support, but I can't say much here as I assumed lock-down didn't extend to that degree. That said we're now considering a one-click distribution you can get. Will keep you posted.

@hemanth fantastic! As per Tom, interested in helping with mock-ups or the site implementation?

addyosmani commented 10 years ago

@donaldpipowitch you're not wrong at all.

At the moment generators are written in a way where the technical decisions about the stack being used (boilerplate, libraries, preprocessors) are decided by generator authors. There are generators which try to offer more choice in this area via prompts, but right now the responsibility for enabling this comes down to individual projects. We're working on a solution which will improve this.

It's called composability and will enable the community to write small, succinct generators which can be easily called from one another and extended. This will make it trivial for a generator to prompt you for the choices you might like to use and have them correctly scaffold out what you are after. It'll also hugely enable reusability without the need to necessarily fork.

hemanth commented 10 years ago

@addyosmani I would be happy to take up the implementation part :smile:

donaldpipowitch commented 10 years ago

@addyosmani I'm sorry. I didn't notice this was about yeoman.IO and not yeoman as a project. Thank you for your feedback. "composability" sounds very nice and I'm looking forward to keep up to date with yeoman generators!

sindresorhus commented 10 years ago

We shipped the new yeoman.io. If there's anything mentioned here not implemented, please open tickets on https://github.com/yeoman/yeoman.io

Thanks all for your input :)