What really bothers me with the docs is that there aren’t examples for everything. In the basic docs there are examples for event functions for example, whereas there is no example in the full docs. So I actually go back to the basic docs when I’m looking for an example.
This would save a lot of time googling and asking stuff on IRC. According to the docs you update user profile data with createUser and Meteor.users.update … I’ve been fiddling around with this for 30 minutes now. After figuring out how to update properly I still have rights problems with access denied for the profile update, which according to the docs is allowed by default. Ergo I am not doing it how it is supposed to be done. If there’d be an example instead of just referring to a function without example I probably would have spent 3 minutes on this instead of 30.
I think it would be really cool if it were easier for the community to contribute to the docs and submit examples, questions, and comments. Do you think that would help?
I like the idea of more examples with community curation, but would suggest hiding the examples in an accordion or other UI element to keep the docs as a clean API reference
Maybe the question is: what do we we mean with “docs”?
I would go with a separation of a clean API reference to quickly look up methods etc, and an extensive guide, which covers how the meteor magic works with examples and how-tos. I think the Rails guys do it pretty well:
Yes, Manual needs some love, especially post 1.0. The community could probably help with keeping it current moving forward, even if it’s just flagging bits to review
Def needs some examples.
For instance(im a huge noob btw) http://docs.meteor.com/#/full/blaze_if nowhere states how we should use it, like closing it and stuff, and then you have to go and google examples
. Splitting reference and examples seems legit.