Skip to content
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

The Docs #1276

Closed
m-ret opened this issue Jul 28, 2015 · 28 comments
Closed

The Docs #1276

m-ret opened this issue Jul 28, 2015 · 28 comments
Labels
docs Improvements or additions to the documentation

Comments

@m-ret
Copy link

m-ret commented Jul 28, 2015

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
Copy link

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
Copy link
Author

m-ret commented Jul 28, 2015

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
Copy link
Member

hai-cea commented Jul 28, 2015

@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
Copy link
Author

m-ret commented Jul 28, 2015

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
Copy link
Contributor

jkruder commented Jul 29, 2015

@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
Copy link

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

Very good work guys with the framework

@Zadielerick
Copy link
Contributor

@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
Copy link
Contributor

jkruder commented Jul 30, 2015

@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
Copy link
Contributor

@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
Copy link
Contributor

jkruder commented Jul 30, 2015

@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
Copy link
Contributor

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

@jkruder
Copy link
Contributor

jkruder commented Jul 30, 2015

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

@jkruder jkruder added the docs Improvements or additions to the documentation label Jul 30, 2015
@m-ret
Copy link
Author

m-ret commented Jul 30, 2015

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
Copy link
Contributor

jkruder commented Jul 30, 2015

@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
Copy link

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
Copy link
Member

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
Copy link
Contributor

@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
Copy link
Contributor

sloria commented Nov 21, 2015

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
Copy link
Member

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
Copy link

@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
Copy link
Contributor

@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
Copy link
Member

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

@alitaheri
Copy link
Member

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

@oliviertassinari
Copy link
Member

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
Copy link
Member

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

@shaurya947
Copy link
Contributor

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

@oliviertassinari
Copy link
Member

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

@oliviertassinari
Copy link
Member

Sorry, but it is true.

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Improvements or additions to the documentation
Projects
None yet
Development

No branches or pull requests

10 participants