I know this is very _very_ douche-baggy but I'm going to share it anyways just in case it's not been mentioned and it's purely in a constructive manner 🤙
First - react-select is freaking rad, thank you @JedWatson for all the continuous hard work and effort on this open source React component!
The website and DOCS SUCK. They're terrible to get a clear understanding of what props belong to what components and how the hierarchy flows. If it wasn't for the examples provided I would never have been able to hack together anything working with react-select.
I know it's annoying for people to comment things like this and I'd be annoyed if someone posted on one of my repos the same and didn't at least suggest a solution or alternative.. so, IMO the docs website that's used for Redux-Saga (and many others) are great and easy to navigate as well as compartmentalize information in categories 👍🏽(https://www.gitbook.com/)
crobinson42
All 8 comments
Haha, thanks for the constructive approach @crobinson42 🙂
I know it's hard to follow. There's way too much to explain, and we did our best at the time.
I checked out gitbook and it's nice they're free for open source, but I think it's valuable to have our docs stored and versioned with our code - makes it easy for people to contribute, and synchronice code and documentation changes together with reviews going through github and our netlify preview deploy system.
Also I think embedding examples in the docs (with the open in codesandbox feature as well) is really important, and gitbook supports markdown but not with react embedded in it.
Having said that, I'm really interested in some of the newer documentation tools coming out like docz, which use mdx.
But also it sounds like the core of your complaint is information architecture; we can redesign the website, and/or improve the content, without any technology change necessary. If you've got suggestions from a user's perspective on what would make our docs easier to understand, that would be great!
JedWatson
on 16 Apr 2019
I'm going to echo this comment. One very simple thing that would help:
http://jedwatson.github.io/react-select/
All the [Source] links are broken!
e.g.:
https://github.com/JedWatson/react-select/tree/master/examples/src/components/States.js
Please fix this!
scottschafer
on 20 Apr 2019
I echo scottschafer's comment above. I'm trying to use select in an edit form but I can't seem to get the existing option selected. I was pretty excited when I saw that the first example seems to do what I want but very disappointed with the 404 I got on clicking the 'source' link.
jimwhurr
on 24 Apr 2019
@scottschafer @jimwhurr as stated in the README.md:
The old docs and examples will continue to be available at v1.react-select.com.
Rall3n
on 24 Apr 2019
Thanks
On Wednesday, 24 April 2019, Rall3n notifications@github.com wrote:
@scottschafer https://github.com/scottschafer @jimwhurr
https://github.com/jimwhurr as stated in the README.md:The old docs and examples will continue to be available at
v1.react-select.com.—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/JedWatson/react-select/issues/3512#issuecomment-486240392,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AIDOEQ224CDGSR5BEBEYA4DPSBQLXANCNFSM4HFZKQ4A
.
jimwhurr
on 27 Apr 2019
The biggest problem for me isn't the broken links or the documentation format, it's the structure of the content. Ideally, the docs would start out with a summary of the main interfaces, and examples of how I would use them. Instead, they start with "Internal Types" and "StateManager Props", two interfaces to which I don't even have direct access.
mgummelt
on 9 Aug 2019
Erik just upgraded his react-final-form api/docs site and it's a very clean look and feel, he's a great guy to ping for ideas too, i'm sure he'd point in the right direction.
https://final-form.org/docs/react-final-form/api
crobinson42
on 9 Aug 2019
Greetings, in the interest of closing stale issues, I will be closing this. There is a catch all issue https://github.com/JedWatson/react-select/issues/3006 currently being used to identify gaps in documentation.
It's likely that the documentation could be a valid discussion in the Discussions section, but if anyone has more constructive elements or missing items to contribute, please feel free to add there.
ebonow
on 20 Dec 2020
Related issues
yrabinov
·
3Comments
mbonaci
·
3Comments
MalcolmDwyer
·
3Comments
ericj17
·
3Comments
steida
·
3Comments
Most helpful comment
Haha, thanks for the constructive approach @crobinson42 🙂
I know it's hard to follow. There's way too much to explain, and we did our best at the time.
I checked out gitbook and it's nice they're free for open source, but I think it's valuable to have our docs stored and versioned with our code - makes it easy for people to contribute, and synchronice code and documentation changes together with reviews going through github and our netlify preview deploy system.
Also I think embedding examples in the docs (with the open in codesandbox feature as well) is really important, and gitbook supports markdown but not with react embedded in it.
Having said that, I'm really interested in some of the newer documentation tools coming out like docz, which use
mdx.But also it sounds like the core of your complaint is information architecture; we can redesign the website, and/or improve the content, without any technology change necessary. If you've got suggestions from a user's perspective on what would make our docs easier to understand, that would be great!