Refresh yeoman.io in 2014

[addyosmani]

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:

• Improve above-the-fold content on the homepage - we should explain what Yeoman is and why you would use it without users needing to scroll down. GruntJS.com does this well. We don't. We should also make the homepage nice and visual. It's wayyyy too much text right now. Keep it simple and to the point.
• Better surface the community generators page. Our ecosystem is growing and is increasing becoming a large reason why devs want to use us. Rather than being buried somewhere in the sidebar, 'Generators' should be a top of the page menu item. Again, GruntJS.com achieves this with their 'Plugins' page. We could also improve the general layout of the generators page and surface metadata in a more pretty way.
• Our Generator API docs could be better highlighted on the site. Rather than being treated as second-class citizens, making them more central (again, top-level items maybe?) might encourage more generator authors to help us improve the docs as they work on their generators.
• Make better use of the blog for our changelogs/releases. We actually tend to make releases every few weeks of either individual generators or yo/generator system. This largely tends to be something the team and generator authors eventually discover, but we could highlight new releases on the site more often. Pushing something new? Why not do a quick blog post about it? It should be super-simple.
• Who is using us? We've never tried to really document this on the site. I know at the moment eBay, Yahoo, Google and a bunch of other companies are exploring using us for some prototyping if not already started. We could better surface this information, maybe even on the homepage.
• [x] Dogfooding. It's been brought up before that we didn't use Yeoman to build the site. There are tons of Jekyll, Ghost and other static site generators available today that we could use to fix that. Would love to see us make use of one to create the new version of the site.

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]

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

[sindresorhus]

Agree to everything

[Joe8Bit]

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]

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]

+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,

• How to deal with common errors while installing Yeoman and its generators.
• Edge cases in which Yeoman may or may not work.
• Requirements before installing the tool. etc.,
• Video walkthrough (already present).

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]

@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]

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]

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]

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

[patelnarendrab]

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

[gazzu]

thanks for the amazing work!!!

[gavriguy]

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

[danielchatfield]

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]

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]

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

[mayhemds]

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

[SBoudrias]

@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]

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]

@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]

@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]

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]

+1 for MEAN generators

[mayhemds]

@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]

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]

Count me in!

[donaldpipowitch]

@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]

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]

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]

@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]

@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]

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

[donaldpipowitch]

@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]

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 :)