Have full docs with examples


#1

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.


#2

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?


#3

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


#4

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:

http://api.rubyonrails.org/
http://guides.rubyonrails.org/


#5

@wursttheke Boath Rubyonrails API and Guides are clean and clear! Especialy the API i find useful, show source or jump to GitHub.


#6

Agreed on keeping the two separate now you mention it. Sounds like a maybe a ‘basic’ version of the Meteor manual could serve the purpose

I really like the way Laravel handles this


#7

@rhyslbw Oh, yeah right. I totally forgot about the Meteor manual. Don’t know how up-to-date is is though. It still refers to Deps instead of Tracker. :wink:

There’s also the Github Wiki which has quite some interesting articles / infos.


#8

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


#9

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


#10

I like your suggestions :slight_smile: . Splitting reference and examples seems legit.


#11

Can we, as the community, chip in and create a (meteor) site where:

  • we have alist of all the topics from http://docs.meteor.com/#/full/topic-name (by automatically parsing it and linking to relevant sections)
  • members can submit short examples
  • other members can up/downvote on examples

Something similar to telescope but streamlined to reflect the meteor documents structure and optimized to browse source code.


#12

Check out the file docs/client/data.js in the meteor repo, no parsing necessary! :smile:


#13

Wow! That’s great. So it should be straightforward to get this up and running. I wonder what the level of contribution would be.