React-router: Docs Improvements

[timdorr]

Our docs aren't faring so well, based on the metric ton of support requests we get here on Github, which are often times one of a common set of issues. This should be fixable with better docs (to an extent! Ignoramuses gonna ignore...).

Now, I know @ryanflorence is working on a tutorial, which sounds pretty awesome, and that will come with some form of docs upgrades. Yay! I'm looking forward to this! But I'd like to be able to contribute to that where I can. And I want to make sure we're clearly inviting other collaborators as well. The more the merrier and the better our docs come out. We can see the benefits of this with Redux, which had a lot of its docs written by contributors besides Dan. So, this issue is to help us do that.

Potential Improvements

• [ ] Documentation website (not just browsing on Github)
• [ ] A version warning ('Warning: These docs are for v4.3.2-rc12-alpha!" A la, kubernetes' docs.)
• [ ] More betterer guides.
• [ ] Filled out Troubleshooting.md
• [ ] Cleaned up Introduction.md
• [ ] More examples and illustrations in API.md (see #2424)
• [ ] All arguments in API must be documented (see #3111)
• [ ] Document how to make a client-side "not found" route (i.e. with <Route path="*" component={NotFound} />)
• [ ] Document how to send 404s from server when using a fallback route
• [ ] Add guide for named components (not just in API docs)
• [ ] Clean up Glossary.md; either get rid of it or sync it up (#3359)
• [ ] Other stuff???

Hopefully, this will inspire community involvement. Documentation is a great way to get involved with open source! It's a lower barrier to entry (no tests! :wink:) and there are a lot of low-hanging fruit available. Also, because it goes right into Github, you get immediate satisfaction once they get merged in. Trust me, it's awesome!

Who wants to help?

[taion]

I'd add "cleaned up, comprehensive API reference, preferably with runnable examples and illustrations".

[timdorr]

Cool, just added that!

[jamischarles]

I'd love to help. May need some light direction as far as what to tackle.

[timdorr]

Troubleshooting.md could _really_ use some love. For that, if you want to just look through closed issues for common problems, you should be able to come up with some better answers than the one we have now.

[ir-fuel]

There is also no explanation in the docs about how to handle routes to non-existing urls

[joemckie]

Just a heads up that import { Router, Route, Link, browserHistory } from 'react-router' in the README doesn't work now. I'm guessing that browserHistory has been deprecated? If that's not expected I can raise an issue with a bug report.

[timdorr]

No, it's for 2.0, which the master docs properly represent.

[joemckie]

Ah, gotcha, I missed that part

[appsforartists]

Hosting the examples would be nice. Nobody wants to check out a repo and install dependencies just to see a demo.

[vinnymac]

I think hosting both the examples and the docs would be a great idea. Although markdown is easy to read, the wiki/file format isn't as friendly. The user experience that could be added with a static docs site is an obvious one, just take a look at Dan's Reflux docs. On top of that it could be built using react-router and the source would in turn be helpful to the community.

[knowbody]

I'm back on the Router, so I will work on it. Will send some PRs soon @timdorr. If you have any extra suggestions please let me know.

[timdorr]

Let's coordinate over Reactiflux (so others can participate too). I've got some things cooking for the static site, including a killer theme for the docs. I've also got some organizational ideas here based on redux's docs.

[tasadurian]

Hey I would love to contribute so I will start working on a documentation site!

[thangngoc89]

I can set up a statinamic for react-router . statinamic uses react-router under the hood. I'm not so good about designing but I'm pretty sure this group can hack together for a great design.

[gaearon]

Per #3111, it would be helpful to have documentation of all arguments (such as nextState) as well as callback signatures in the docs.

[jdelafon]

Please host the docs somewhere else where it can support a 'Search' field. Or display it all in one page, with anchors. Most of the time I have no idea which (sub-)category my question concerns and I have to go through 10 links before I maybe find something, with a huge waste of time (especially since I don't find it in the end as it is still incomplete).

[knowbody]

I'm starting the rewrite here. If I can produce some value to the docs there then we can merge them.

[timdorr]

@knowbody Can you add the team as contributors to that repo?

[knowbody]

@timdorr done

[taion]

To get a few more words than on Twitter, note that @ryanflorence has a pretty good (I think!) tutorial up on https://github.com/reactjs/react-router-tutorial.

I think what we're most missing for something like a docs rewrite here is less a step-by-step tutorial like https://css-tricks.com/learning-react-router/ (per @mjackson's tweet),, but possibly more of a guide that's well-organized by section.

Something like:

• Here is what you need to know to do basic route configuration
• Here is all the advanced route configuration stuff that you probably don't need to know
• Here is, written out in prose, everything about <Link>s
• Here is everything about server-side rendering, including all the caveats

That sort of thing – essentially prose elaborations of the contents of our API reference, along with examples and explanations.

Just my two cents.

[aweary]

@taion personally I think a document giving a high level overview and reasoning for the overall architecture would be helpful too (kind of like what's mentioned in https://github.com/facebook/react/issues/6335), mostly for people who would like to contribute.

Lower priority probably, but might be worth thinking about.

[taion]

@Aweary Certainly. I'm just highlighting where I see detailed docs as useful given the presence of a tutorial and an API reference. Because in some sense that's what the "docs" in this repo should be – not the tutorial, and not the API reference either.

[aweary]

@taion yeah I totally agree, it's important to organize information for users appropriately. Just chiming in for future reference :smile:

[taion]

@knowbody BTW, I'm going to make a few quick updates to the troubleshooting guide. Hopefully that won't overlap with what you're working on.

[knowbody]

Yeah that's fine. Treat the docs in my repo as a separate thing. I'm
rewriting the docs completely, might use some bits and pieces from the docs
in this repo. Don't treat them as part of this repo yet.

I should've kept my repo private and only make it public once it's done.

[ybot1122]

Hi. You just merged my first ever open-source contribution. Thanks! I'd like to share my journey.

It's a lower barrier to entry

Agreed. Helped me also isolate a singe flow of logic to follow. I feel much more confident to dive into the source code now.

there are a lot of low-hanging fruit available

Yes.

you get immediate satisfaction once they get merged in. Trust me, it's awesome!

[seanjh]

Can someone explain why the master documentation does not cover the currently released version? I think it's reasonable for the average user to expect that the documentation on master will cover the version installed when they properly follow the installation instructions.

Specifically, if a new user visits this repo today and follows your instructions for installation they will receive version 2.3, while the documentation on master all covers version 2.4. This disconnect should either be made perfectly clear at the very top of the documentation, or the documentation for the upcoming release should be kept outside of master until release. The most glaring issue today of is the withRouter change. Sure, there's a (hardly noticeable) deprecation notice in the API docs, and an indication of sorts that the master HEAD is unreleased in CHANGES.md, but all this information is buried deep in documentation.

edit: it appears this issue has been raised before (e.g., #3378)

[taion]

It's noted here as the second item on the checklist, and we're aware of the issue. If you'd like to help us set up the tooling to add appropriate release-specific annotations, then we'd be happy for that help.

[seanjh]

Cool! Didn't realize that action item covered this issue. Thanks @taion. Would love to contribute to this project, if possible. I'll take a look when I have a chance at the referenced solution.

[theianjones]

Hey! I'd love to help with this. Is there any part of the documentation (like finding common closed issues or something) that I can help with?

[HoraceShmorace]

It would be nice if the examples had READMEs to explain exactly what's going on in each.

[Bigguy34]

Question, I am looking for docs on applyRouterMiddleware, but I can't find a centralized location for this HOC. I see it here in code and also a merge with some vague comments on how to use it, any suggestions on where to look for docs on the middleware functionality in react-router?

[taion]

There aren't any right now.