-
-
Notifications
You must be signed in to change notification settings - Fork 10.2k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Docs Improvements #2933
Comments
I'd add "cleaned up, comprehensive API reference, preferably with runnable examples and illustrations". |
Cool, just added that! |
I'd love to help. May need some light direction as far as what to tackle. |
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. |
There is also no explanation in the docs about how to handle routes to non-existing urls |
Just a heads up that |
No, it's for 2.0, which the master docs properly represent. |
Ah, gotcha, I missed that part |
Hosting the examples would be nice. Nobody wants to check out a repo and install dependencies just to see a demo. |
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 |
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. |
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. |
Hey I would love to contribute so I will start working on a documentation site! |
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. |
Per #3111, it would be helpful to have documentation of all arguments (such as |
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). |
I'm starting the rewrite here. If I can produce some value to the docs there then we can merge them. |
@knowbody Can you add the team as contributors to that repo? |
@timdorr done |
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:
That sort of thing – essentially prose elaborations of the contents of our API reference, along with examples and explanations. Just my two cents. |
@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 facebook/react#6335), mostly for people who would like to contribute. Lower priority probably, but might be worth thinking about. |
@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. |
@taion yeah I totally agree, it's important to organize information for users appropriately. Just chiming in for future reference 😄 |
@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. |
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.
|
Hi. You just merged my first ever open-source contribution. Thanks! I'd like to share my journey.
Agreed. Helped me also isolate a singe flow of logic to follow. I feel much more confident to dive into the source code now.
Yes.
|
Can someone explain why the Specifically, if a new user visits this repo today and follows your instructions for installation they will receive version edit: it appears this issue has been raised before (e.g., #3378) |
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. |
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. |
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? |
It would be nice if the examples had READMEs to explain exactly what's going on in each. |
There aren't any right now. |
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
<Route path="*" component={NotFound} />
)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! 😉) 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?
The text was updated successfully, but these errors were encountered: