README rewrite

[nateabele]

Hey guys,

I just spent some time rewriting our README file. Since it's kind of the project homepage at this point, I figured it'd be worth a little investment. You can preview it here.

The highlights, in brief:

• More cohesion and better flow between sections
• Consistent voice, use of tenses, and overall consistency of style
• Code examples have been updated to reflect best practices and new features
• Top-level navigation lists related pages
• A section that instructs people on the proper way to report issues

Things we still need:

• All the plunkr examples need to be updated! @timkindberg you've got some kick-ass templates already, but they need to be updated and cleaned up a bit — ping me on IRC if you'd like to work together on this
• We need a real Contributors section to better convey project goals & philosophy, expectations and standards for code contributions, roadmap link, etc.

Did I miss anything?

[timkindberg]

I'm on IRC right now

[timkindberg]

Wow I really like it! Oh man, I have some qa items:

General:

• One of the main reasons people will revisit our page is to access the guide and api ref, so I actually think it needs to be added to the top level nav, or a sub level nav. Somewhere towards the top. I do see how this can make it too busy up there though too, what are your thoughts?
• If we use the <ui-view> element instead of attribute on a <div> then we'll also have to set ui-view display to block. Not sure if its worth the extra css file or inline style.
• We could also link to the milestones landing page in the Contributors section. Our roadmap is kind of a mess, so the milestones may be a better alternative.

Nested States & Views:

• (2), double word "app app"
• Indentation on (5) code example is wonky. "state2" should be same indent as "state1", same with their children.

Multiple & Named Views:

• (2), ui-views have </div> as closing tags
• I forked the plunkr (I forked it good too) and changed it to not use templateUrl, now it uses template instead. http://plnkr.co/edit/SDOcGS?p=preview. It shows off template and makes the example quicker and simpler to review.

[eahutchins]

I second moving the API links to the top to make them easier to get to.

You might want to mention that with named views and a views: config the state's view isn't used (actually it would make more sense to me to merge the state view configuration into views: as the default unnamed view).

[nateabele]

Good thoughts, I'll update it later today. Totally agreed about docs being top-level.

If we use the <ui-view> element instead of attribute on a <div> then we'll also have to set ui-view display to block. Not sure if its worth the extra css file or inline style.

Weird, I never noticed that. I'll update accordingly.

@timkindberg for those other corrections, feel free to push additional commits to that branch if I don't get to them first.

I'll hop on IRC later today and we can go through all the different Plunkrs we'll need. I'll shoot you an email to coordinate time.

[timkindberg]

Ok cool. I may not be available til late like 9 or 10pm.

[nateabele]

@eahutchins

You might want to mention that with named views and a views: config the state's view isn't used

Technically speaking, there's no such thing as the 'state's view', per se.

[A]ctually it would make more sense to me to merge the state view configuration into views: as the default unnamed view

Under the hood, that's exactly what happens: https://github.com/angular-ui/ui-router/blob/master/src/state.js#L65-L73

Maybe we can figure out a better way of explaining this.

[eahutchins]

@nateabele it's what happens unless you specify views:, I'm saying that if you have both the state and views: config they should be merged (it seemed really weird to me that the views: completely replaces the "main" definition in the state). At any rate spelling this out is probably a good idea.