The Docs

[m-ret]

I am here to express what a lot of people is talking when you put a question online asking about this library, and what everybody says: The Docs are horrible.

We all are sad, your framework is nice. But you are missing a bunch of stuff there in the Docs. In every example you should put IN DETAILS, how to have running the components. And also, update it to ES6, that is what we are using in React, ES6. You are still doing var X = require('x'); so what is going on there? Haven't you think on the Junior Devs? They are lost, I include myself, I am lost.

You are the ones who made the framework so you totally understand what is going on, but should update the Docs, it is very important. I was yesterday in Slack, and all of my co-workers are extremely sad because we are going to switch to Materialize or Polymer, possibly.

You really need to update the Docs, and put some extra details.

Sorry, but it is true.

[ayozebarrera]

I already ask it, but the reply was "The docs are up to date".

At first, When I was learning React, following the mui docs, I NEVER won. I had to go to docs src and try checking code and if not... new issue type question ^^

So.. I'm with @maketroli, +1 to the update.

[m-ret]

yes @ayozebarrera, yesterday I was at the src code of the framework and anyways I couldn't complete the task I was working on. The senior Dev is still struggling with it. It is a great framework, but without good Docs, you guys will be losing this run.

[hai-cea]

@maketroli @ayozebarrera Thanks for the feedback guys. I totally agree that the docs are lacking. We've been doing a lot of work on the library itself and the docs have been lagging behind - so I'm sorry about that.

We would love any help on improving the docs though. We have several issues related to docs and it would help greatly if you can open up issues on specific documentation changes/additions. We'd also love a PR as well! :)

Again, I'm sorry that the current documentation has caused you some frustration. Hopefully, the docs will just get better over time and we can redeem ourselves. :)

[m-ret]

hey @hai-cea thank you, do not take it bad. It is just feedback. Have a nice one and we'll be waiting for the docs update.

[jkruder]

@maketroli @ayozebarrera @hai-cea What do you guys think about creating something similar to what the bootstrap folks did for their react-bootstrap page: http://react-bootstrap.github.io/components.html? The 'Show Code' button displays the code used to generate the example and the user can then edit the example and see the changes applied in real time. I think that will take interactivity to the next level and really make our docs pages useful.

If someone is interested, the magic appears to be in https://github.com/react-bootstrap/react-bootstrap/blob/master/docs/src/ReactPlayground.js. which is used in https://github.com/react-bootstrap/react-bootstrap/blob/master/docs/src/ComponentsPage.js. There will be some work making this fit our docs structure but it should be doable.

[ayozebarrera]

Sounds great for me, I like it. Real time ftw 👍

Very good work guys with the framework

[Zadielerick]

@jkruder I was actually working on that. I have been trying to implement react-live-edit into the docs, so as soon as I get the component implemented, I will start the process of adding it to each component on the docs site. This is the one I was planning on using, let me know if which ya'll prefer: https://github.com/joelburget/react-live-editor

[jkruder]

@Zadielerick Perfect! I like the interactivity of the react-bootstrap implementation. It hides the code by default and then expands downward so that you can edit it. If the react-live-editor can work like that I'd be happy with it.

[Zadielerick]

@jkruder I would like to get any of the live editors to work, and after looking at the bootstrap one, I would also prefer it over the react-live-edit. I also like this project if I could get it to work. I have tried adding like 4 different live editors with no luck :( Any help or suggestions are very welcome

[jkruder]

@Zadielerick I like that one too, looks similar to the react-bootstrap one. I'll take a crack at it and see if I can get something to work -- probably wont be until this weekend.

[Zadielerick]

@jkruder Cool, Thanks. In the mean time I will do my best to try to get something working.

[jkruder]

@Zadielerick Sounds great, let me know if you get something working, I'd like to check it out.

[m-ret]

I will like to take part of this but I am working in 3 different projects. As soon as I get done with one of those, I will be placing some PR's over here. Have a nice coding.

[jkruder]

@maketroli Thanks! That would be great! @Zadielerick and myself will let you know when we have the live editing incorporated and then we can start divvying up the rest of the docs pages.

[laurenskling]

What is the status on this issue? I just started trying the AppBar by following the documentation. It's in many ways not up to date with the product. I had to dive deep into the code to see what was wrong to find out the functionality of components (e.g. MenuItem) are different from the documentation.

[oliviertassinari]

The Docs are horrible

We could improve the docs by an order of magnitude.

I had to dive deep into the code to see what was wrong to find out the functionality of components (e.g. MenuItem)

I agree, you have to import the new MenuItem and not the older one. For someone that start, this is very confusing.

For instance, IMO their doc is better: http://react-toolbox.com/#/components/autocomplete

[shaurya947]

@laurenskling if there's things that you noticed that could be improved (be it with the AppBar doc only), I encourage you to write a PR to suggest those changes..

[sloria]

It's a bit strange that the docs use const (an ES6 keyword) but use ES5 require instead of import. Would be nice to see this changed.

If the maintainers give the go-ahead, I could take a stab at a PR.

[oliviertassinari]

It's a bit strange that the docs use const (an ES6 keyword) but use ES5 require instead of import.

The source code use a mixed of import and require. Yes it's strange and I think that we should use import over require everywhere.

[laurenskling]

@shaurya947 , the main problem for me is that i don't understand how the docs is telling me to use it. If you look at the appbar: http://material-ui.com/#/components/appbar it tells me to require the appbar, then it states 3 examples, which will not work because you need to import a lot more for those components. And before i found that i had to get the icons out of /lib/svg-icons....
So i would like to help, but it's more then just a bug in the docs, it that i don't know in what way it's trying to help me.

[shaurya947]

@sloria PRs welcome (if you haven't already started on one)

@laurenskling I see what you mean. I guess the current docs just assume that if you see <ComponentName> somewhere, then you know how to (or how to figure out to) import ComponentName -- which is not an assumption I like. For starters, I guess we could add the necessary import statements for every example code. Is that something you could help with by submitting PR(s)?

[oliviertassinari]

This is the first iteration to improve the properties documentation #2382.

[alitaheri]

@maketroli @ayozebarrera Please checkout #2253 and see if this way of generating the docs serve as good documentation.

[oliviertassinari]

I'm working on a second PR to migrate the Avatar. This should serve as a good exampe of how to do it.
If others can help me, that would be awesome.

[alitaheri]

@oliviertassinari I'll try to walk up from Toolbars so that I won't interfere with your work.

[shaurya947]

@oliviertassinari @subjectix looking forward to your PRs so I can see the process 😀

[oliviertassinari]

@shaurya947 Here is the second one with the list of advantages #2407

[oliviertassinari]

Sorry, but it is true.

@maketroli Yes it was true #2433.
Thanks for raising this issue!