Skip to content
This repository

Docs for 1.0 #829

Closed
sindresorhus opened this Issue January 09, 2013 · 52 comments
Sindre Sorhus
Owner

From Addy: Thanks for your interest in the Yeoman docs sprint. We're hoping to spend Wednesday 30th writing lots of shiny new docs for Yeoman and hope you'll join us. Docs are a fantastic way to brush up your skills on a tool and we'll all be in the #yeoman channel on freenode if you need any help. Let us know if you would like to take part.

Sindre: Here is what we need to document for 1.0. Fill in when you find anything.

  • How to switch to use grunt and bower directly. Need to mention users have to do npm install -g grunt-cli bower.

  • How to get pushState to work. Either route all traffic to index.html or set up patterns. Using grunt-contrib-connect together with middleware. (#670 (comment))

  • How to use PHP with Yeoman. Lot's of requests for this. We could show of simple it is. (#270 (comment))

  • How to use Express with Yeoman.

  • How the install command works, and where packages are fetched from and how the users gets them there. Ref #861 (comment)

  • An updated guide on how to write your own generator (#761)

  • How do you get Handlebars and erb templates working with Yeoman?

  • GitHub pages and Yeoman workflow (#850)

  • How does Grunt relate to Yeoman? (#435)

  • Road to 1.0 and other changes since 0.9 (#775)

  • Documentation for Generators (e.g AngularJS)

  • How to get Yeoman working with Bootstrap for LESS

  • Upgrade guide to 1.0. What kind of changes users has to do.

  • How to use Jade, Handlebars.js, LESS, etc with Yeoman.

Frederick Ros
Collaborator

I would also add some basic tutorials, showing a step by step implementation of a simple app. This would allow people to understand both the tool and the directory layout (see in particular http://stackoverflow.com/questions/14211632/where-do-i-put-my-scripts-in-yeoman-project)

Addy Osmani
Owner

I think we should arrange (for sometime before the end of the month) a doc/project sprint to get the documentation updated. We had some help with tutorials at launch and maybe it would be useful to bring some of those authors back in to see how much/what has changed.

Sindre Sorhus
Owner

@addyosmani good idea

Scotty Vernon

+1 @addyosmani good idea.

I took the liberty of answering that question on S.O. I wouldn't mind contributing to the docs.

Addy Osmani
Owner

That would be fantastic @KingScooty. We were thinking of doing a sprint next week :)

Sindre Sorhus
Owner

We're doing the docs sprint on wednesday 30.01 if anyone is interested: https://groups.google.com/forum/#!topic/yeoman-dev/i1XiM-gd18E

Sergey R

@sindresorhus sounds cool!

Sindre Sorhus
Owner

How to contribute

We're open to all kinds of contributions, from simple grammar fixes (I'm sure there are a lot :p) to writing tutorials.

For small changes feel free to just fix directly. It's all in the wiki.

For larger changes or anything other docs related stuff, hit us up on #yeoman on Freenode (IRC, webchat here: http://webchat.freenode.net/?channels=yeoman)

Eric J. Duran

I'm working on "GitHub pages and Yeoman workflow" now.

Addy Osmani
Owner

I'm working on Yeoman/Express and then improving the support documentation. Might take the changes since 0.9 one too if no one else gets to it.

Docs added:

Sergey R

Hey guys. Can someone write a tutorial "How to configure Yeoman to add LESS compilation for Bootstrap" as a one of most popular requested features?

That'll solve 2 problems:

  • reduce duplication of LESS Bootstrap issues
  • teach how to tune Yeoman and Grunt
Addy Osmani
Owner

Working on handlebars/erb templates with yeoman doc next.

Sindre Sorhus
Owner

@mklabs is working on:

  • finishing up the generator API docs (generated from code comments)
  • Quick Start guide on creating a new generator (simple, extended version)
  • mini page on testing generators locally.
Mickael Daniel
Collaborator

I can confirm that. Pushing and testing on my fork at https://github.com/mklabs/generators/wiki

Eric J. Duran

Docs added for "GitHub pages and Yeoman workflow"

Sindre Sorhus
Owner

I will work on some docs for the webapp-generator.

Sindre Sorhus
Owner

We're still in need of docs for the other yeoman generator/projects: https://github.com/yeoman

Sindre Sorhus
Owner

I think @btford is working on some generator-angular docs

Patrick Williams

Proof reading the READMEs one by one. update-notifier done.

Addy Osmani
Owner

Could everyone that kindly worked on docs yesterday (and didn't get a chance to ping the thread with their work) let us know how you got on? I'd love to be able to update the list of items we now have covered.

Peter Herz

Team Y. .. just wanted to note that I've created a shell script that can install yeoman-express apps for you.
You can find it here ... http://pastebin.com/RtSVuFzr

Addy Osmani
Owner

Nice work!

Addy Osmani
Owner

@fgnass I don't suppose you would be interested in exploring PHP support using our newer version of Yeoman, would you? It would make for a great write-up.

Sindre Sorhus

@mklabs how's the generators docs coming along?

Sindre Sorhus
  • Better docs on usemin and how it works.
Addy Osmani
Owner

@sindresorhus

RE "How the install command works, and where packages are fetched from and how the users gets them there."

As we've now moved over to Bower being used independently, should this be deferred to https://github.com/twitter/bower/blob/master/README.md?

Sindre Sorhus

Yes

Addy Osmani
Owner

Thread: I'm currently chasing up the PHP item on this list with an external dev. Would anyone be interested in taking on a short doc to discuss how usemin works and what it does?

Pascal Hartig
Owner
passy commented March 08, 2013

@addyosmani usemin is currently undergoing a larger rewrite by @sleeper.

Addy Osmani
Owner

Thanks for letting me know!

Kevin Mårtensson
Collaborator
kevva commented March 19, 2013

A quick writeup on how to use jade with yeoman, https://gist.github.com/kevva/5201657.

Sindre Sorhus
Owner

@kevva this is great! would you like to add it to the wiki?

Could you be clearer about yeoman just generating an ordinary gruntfile and that you can use whatever grunt tasks you want, including grunt-contrib-jade.

Kevin Mårtensson
Collaborator
kevva commented March 20, 2013

Yep, I'm going to refine it a little, then I'll add it to the wiki.

Addy Osmani addyosmani referenced this issue March 26, 2013
Closed

Meta-bug for task ownership #997

0 of 15 tasks complete
Felix Gnass fgnass referenced this issue in fgnass/gateway April 03, 2013
Open

support documentation #2

Addy Osmani
Owner

Let's do another docs sprint. Maybe at the end of next week or the week after. It would be really nice to fill in some more of these gaps before 1.0 final. Anyone wanna help? :)

Pascal Hartig
Owner
passy commented May 12, 2013

I'm in!

Sindre Sorhus
Owner

Sure

Pascal Hartig
Owner
passy commented May 12, 2013

AoE afterwards? :P

Sindre Sorhus
Owner

Ofc!

I can't until next next sunday though... going away for some days and then conf time.

Addy Osmani
Owner

Can someone with a few free cycles do me a favour? It's been a long time since we posted this issue and many many StackOverflow, yeoman-dev and GitHub issues later I wonder if some of these docs tasks have already been covered elsewhere. At least, those which have not yet been marked as done.

Could someone take on the task of trying to find answers to them so we can at least add partial solutions to the wiki and build upon those in more detail later?

Marcos Hernández

has anyone checked @Thomas-Lebeau Bootstrap-LESS? I think is a good base for writing a step by step tutorial on writing a custom generator, the code seems simple and straightforward to me.
I don't feel confident in yeoman-generator internals to write it myself.

Stephen Sawchuk
Collaborator

This sounds like the best party ever.

Thomas Lebeau

@marcoslhc, in fact the bootstrap-less generator is only an adaptation of the generator-webapp which is at least as clear and simple as mine, and may follow the best practice better. Also check generator-generator to scaffold your generator.

But I agree that the doc for creating generator need to be improved.

Stephen Sawchuk
Collaborator

Please check out yeoman/generator#206 for an on-going discussion of improving the Generator docs. I've been working on a re-write/supplemental walkthrough, which is linked towards the bottom. If you have any feedback, please keep the discussion going :)

Addy Osmani
Owner

@sleeper fantastic work on the recent updates! Do you know what the status is on updated docs for it?

Frederick Ros
Collaborator

@addyosmani I need to review it ... Some stuff are far from being clear from my point of view in the text. I also need to add more "use cases" of usemin usage ...

Sindre Sorhus

We could still use more and better docs if anyone is interested ;)

Paul Freeman

@sindresorhus I'd love to get involved and work on some doc stuff, is there any particular area that you feel would benefit from some attention?

Sindre Sorhus

@OddEssay step-by-step tutorials are always nice, especially video ones. Also take a look at the issue description for the unchecked items.

@addyosmani probably has a better idea of what though.

Addy Osmani
Owner

@OddEssay Thanks for volunteering! There are two main areas that we could use better docs on:

1) User-facing docs: showing people how to practically use Yeoman to build simple applications end-to-end. This could be as simple as picking a generator that's popular and writing a tutorial or multi-part tutorials walking through how to use yo, bower and grunt together to build an app.

2) Generator-author docs: we're always happy to receive docs contributions for our generator system. You'll find that there are lots of questions about how to do X in the issue tracker or Stack Overflow and better documenting common answers to questions in the generator docs would be hugely useful.

Hayden Bleasel haydenbleasel referenced this issue in yeoman/generator-webapp January 06, 2014
Merged

Refactoring CSS Pre-Processing #238

Addy Osmani
Owner

Most of the issues for the 1.0 docs sprint have docs now and we've started tracking what new docs we would like authored over in #1259. If you're interested in helping out, please hop over into that thread :)

Addy Osmani addyosmani closed this January 09, 2014
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.