Docs for 1.0 #829

Closed
sindresorhus opened this Issue Jan 9, 2013 · 52 comments

Comments

Projects
None yet
Owner

sindresorhus commented Jan 9, 2013

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.
Contributor

sleeper commented Jan 10, 2013

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)

Owner

addyosmani commented Jan 10, 2013

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.

Owner

sindresorhus commented Jan 10, 2013

@addyosmani good idea

+1 @addyosmani good idea.

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

Owner

addyosmani commented Jan 24, 2013

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

Owner

sindresorhus commented Jan 28, 2013

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

@sindresorhus sounds cool!

Owner

sindresorhus commented Jan 30, 2013

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)

Member

ericduran commented Jan 30, 2013

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

Owner

addyosmani commented Jan 30, 2013

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:

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
Owner

addyosmani commented Jan 30, 2013

Working on handlebars/erb templates with yeoman doc next.

Owner

sindresorhus commented Jan 30, 2013

@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.
Contributor

mklabs commented Jan 30, 2013

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

Member

ericduran commented Jan 30, 2013

Docs added for "GitHub pages and Yeoman workflow"

Owner

sindresorhus commented Jan 30, 2013

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

Owner

sindresorhus commented Jan 30, 2013

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

Owner

sindresorhus commented Jan 30, 2013

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

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

Owner

addyosmani commented Jan 31, 2013

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.

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

Owner

addyosmani commented Jan 31, 2013

Nice work!

Owner

addyosmani commented Feb 4, 2013

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

Owner

sindresorhus commented Feb 5, 2013

@mklabs how's the generators docs coming along?

Owner

sindresorhus commented Feb 18, 2013

  • Better docs on usemin and how it works.
Owner

addyosmani commented Feb 19, 2013

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

Owner

sindresorhus commented Feb 20, 2013

Yes

Owner

addyosmani commented Mar 8, 2013

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?

Member

passy commented Mar 8, 2013

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

Owner

addyosmani commented Mar 8, 2013

Thanks for letting me know!

Member

kevva commented Mar 20, 2013

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

Owner

sindresorhus commented Mar 20, 2013

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

Member

kevva commented Mar 20, 2013

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

Owner

addyosmani commented May 12, 2013

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

Member

passy commented May 12, 2013

I'm in!

Owner

sindresorhus commented May 12, 2013

Sure

Member

passy commented May 12, 2013

AoE afterwards? :P

Owner

sindresorhus commented May 12, 2013

Ofc!

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

Owner

addyosmani commented May 17, 2013

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?

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.

Contributor

stephenplusplus commented May 27, 2013

This sounds like the best party ever.

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

Contributor

stephenplusplus commented May 27, 2013

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

Owner

addyosmani commented Jun 9, 2013

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

Contributor

sleeper commented Jun 10, 2013

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

Owner

sindresorhus commented Nov 6, 2013

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

OddEssay commented Nov 6, 2013

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

Owner

sindresorhus commented Nov 6, 2013

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

Owner

addyosmani commented Nov 6, 2013

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

Owner

addyosmani commented Nov 6, 2013

@haydenbleasel haydenbleasel referenced this issue in yeoman/generator-webapp_DEPRECATED Jan 6, 2014

Merged

Refactoring CSS Pre-Processing #238

Owner

addyosmani commented Jan 9, 2014

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

@addyosmani addyosmani closed this Jan 9, 2014

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment