Better docs/tutorials

[kaumac]

First of all, let me congratulate and thank you on your awesome work on the UI-Router port.
I worked with Angular 1.x for few years and UI-router was my "go to" router, and coming to React I found React router to be a pretty cheap router implementation (unstable API, routes bound to URL instead of state, etc), but it seems to be the most used by the community.

I believe UI-Router has the potential to do for the React community what it did for the Angular community, but it really needs better documentation and well written tutorials to encourage people to start using it. I almost gave up on UI-Router because I couldn't find a way to programmatically changing the state, it doesn't say anywhere that the "transition" object is passed to the route's component as a prop.

The fact that lot's of the React wrapper docs point to the core router docs doesn't help a lot, as I believe that kills the purpose of having a react wrapper that abstracts ui-router to work in a "react way".

Please don't take any of this as criticism, its just a feedback as I'd really love to see ui-router as the "default" routing solution for React. And again, congrats on the outstanding work on wrapping UI-Router for React, and please let me know if there's anything I can help with.

[elboman]

Hi,
Thank you very much for the feedbacks!
I totally agree with you, we really need to create good documentation and tutorials to help people understand the possibilities with UI-Router and how to achieve common practices with the router.

@christopherthielen helped me set up typedoc and I started documenting the source to generate friendly API doc on the website, but it's still a WIP.

Once I'm done and 0.5.0 is finally out, I will focus on tutorials and general purpose docs.

Unfortunately I'm in the middle of moving abroad and these days have been really busy so I struggle to find the time right now, but once I'm set I'll finally be able to dedicate some stable work.

In the mean time and in general, would you like to help with this task? We could start defining a list of priorities for the project in terms of features and documentation in order to create a roadmap and ease the process of contributing for people who wants

[kaumac]

No problem @elboman, I totally get it, I recently moved from Brazil to Denmark and I know how much time and energy it takes to move abroad.

As to contributing to the documentation, I'd love to. I don't have a lot of free time these days, but I can definitely contribute some of it.

I think having an API documentation is great once you get the hang of how the library works, but for completely new beginners it can be a bit frustrating not having a high level "5 minutes setup" guide to get the feeling of the library.

I was thinking we could have something like the React Quickstart docs, which are great for people completely new to React and approaches the most important topics for beginners in a very intuitive way. In that sense, there could be examples on how to install, register routes, transition between them, explaining the concept of routes as states and abstract states, etc.

What do you think?

[christopherthielen]

In that sense, there could be examples on how to install, register routes, transition between them, explaining the concept of routes as states and abstract states, etc.

I think that's the intention of the tutorial series. Perhaps we missed the mark there? Maybe a good approach is to think how the tutorials can be improved?

https://ui-router.github.io/react/tutorial/helloworld

[kaumac]

@christopherthielen I do agree that tutorials get the job done somehow, but I still think there should be more granular and "to the point" guides.

The helloworld tutorial imho covers too much unnecessary information that are unrelated to the library (like module loaders, creating react components, etc) and too little of the important, library related informations, like how to access the transitionobject, how to redirect programatically, the differences between url based routing and state based routing. There could also be information like @elboman pointed on the differences between ui-router and react router and the benefits of ui-router (for those new to it).

I guess my point is that there should be granular guides like in React docs (eg. Rendering Elements, Components and Props, State and Lifecycle, etc) with in-depth explanation on each topic. This way all information is easy to find without looking through the tutorial or guessing/reasoning with the code in the examples.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. This does not mean that the issue is invalid. Valid issues may be reopened. Thank you for your contributions.

[stale]

This issue has been automatically closed.