matter-js
matter-js copied to clipboard
liabru
Documentation Lacks Code Examples
I've been learning MatterJS recently for work on a research project, and although the documentation is alright and explaining methods and properties, it always just links to giant JS files for examples, rather than short snippets. I'd use a nice reference tutorial from Google as a good example of using snippets of code to explain how stuff works. This might
I would like to help improve the documentation on MatterJS, since I am using it pretty extensively for the next little while, but I could not find a repository for the documentation, so feel free to point me to that so I can migrate this issue over there.
Why not directly contribute to README or the WIKI PAGE directly? Also can you share an example documentation of someother projects you liked, probably we can structure information in this project as per your example.
Although the wiki and README are useful, in actually learning the nitty gritty of MatterJS I've found the core documentation to be really important, so that's where I think work would be the most useful. Is the documentation site closed source then? If so, can I inquire why that is and if it can possibly change?
Also, per your request, some examples of good documentation (in my opinion):
- jQuery Slide Toggle - live demos, source code, and method specifications are all on this one page, which means it's useful as a starting point for using the function or as a place to look up advanced options.
- Google Visualization API - Query - this is a more technical example, and explains the nitty gritty of an individual class in the Google Visualization API. However, it documents the options hash very well and all of the properties of the class in a nice table.
- EmberJS API - Checkbox - this is part of the API docs for EmberJS, and is broken up pretty well. The main benefit is that it is more than just specifications, lots of the methods and properties have examples so you can better understand them.
For time being, you can give a try looking at the source code itself. I am jus starting out on matterjs for a fun project and learnt few things easily by looking at the needed source.
My concern is not my own personal learning (as I can make do and figure stuff out), but rather for the state of the documentation itself. I appreciate the tip though.
@liabru - you seem to be the one hosting the documentation site. Could you give your input on this?
Outside of the documentation and the wiki, there are also many examples which are the main for learning the features. Are these not sufficient to get started?
I'd use a nice reference tutorial from Google as a good example of using snippets of code to explain how stuff works.
A decent tutorial is on my todo list for the wiki but for now there is Getting Started.
Is the documentation site closed source then? If so, can I inquire why that is and if it can possibly change?
The documentation theme currently is not shared but it pulls the content directly from the comments in the source code like this one using yuidoc. So it's possible to improve the documentation through pull requests.
I also think it's possible to embed examples into the docs, but I'm not sure how valuable examples for each function will be, since most are straightforward. What's more difficult is putting many of them together, so I'd prefer more pages in the wiki for now I think.
I'd also say that engine deliberately follows a pretty standard architecture that should be familiar to those who have used physics or game engines before, which is why I've not gone in to tons of detail on it (since I have limited time, I prefer to spend it on fixes and features).
I think the best example of the challenges I have faced with the documentation is that except for the wiki, the documentation doesn't cover a lot of core things. As a specific example, the documentation for World on the MatterJS documentation site doesn't seem to have the World.add function that is critical to using MatterJS. It's also not helpful to have a standard architecture for people who are just starting out, though I think it is fair that you want to focus on developing features.
Personally I prefer the site to the wiki for documentation (it has more content and is better laid out since it is project specific), so if there is any way to help improve that site I would be very interested. If not, I think I will start writing tutorials and documenting important functions in the wiki to help lower barriers to entry and make it easier to pick up and use MatterJS for any project.
I am playing with matterjs recently probably I can share my experience as tutorials if that helps.
the documentation doesn't cover a lot of core things
Well, it should at least list almost 100% of the code base, are you saying there's a lot of unlisted functions or modules? I feel that's a little unfair.
As for detailed documentation, I'd say it covers 90% of the core features most users are using in reasonable detail. Some of the internal modules have limited documentation because the vast majority of users won't use them directly, though I do aim to document those eventually.
Can you give more examples of what's missing?
As a specific example, the documentation for World on the MatterJS documentation site doesn't seem to have the World.add function that is critical to using MatterJS.
Looks like there's a bug in the documentation. This part on the Matter.World docs:
Matter.Composite.add(composite, object) → Composite Inherited from Composite:
Is meant to say Matter.World.add like the other aliased functions do, so this needs fixing, thanks for raising.
It's also not helpful to have a standard architecture for people who are just starting out, though I think it is fair that you want to focus on developing features.
I'm not sure what you mean?
Personally I prefer the site to the wiki for documentation (it has more content and is better laid out since it is project specific), so if there is any way to help improve that site I would be very interested.
You can pull request improvements to the docs since they are in the code (see my last comment), and I will regenerate the site when they get updated.
@liabru - my bad then, I guess that was just one really important function that wasn't documented. Overall it covers functions fairly well in terms of core documentation, it's just examples (both live and code snippets) that would make it really useful. The other challenge I have with the API is that it's hard to find intuitively where a function might be if I just know the end result I am trying to achieve (like if I know I want to check for Bodies within the Bounds of another Body, do I look at Body, Bounds, or Engine? Answer: Look at Matter.Query).
Again I think at this point that the biggest help would be to just write out tutorials that people can use to get started with basic applications of MatterJS. Even just writing out how to build the neat demos you have would be super useful, and I am more than happy to work on that in the wiki, but it seems to me that the site you have would not support images, code snippets, and live examples, which is how I would see it being enhanced best. Thus the wiki is truly the best option for helping beginners get more acquainted with MatterJS.
Also in regards to the standard architecture, I would point out that you a standardized system only helps people who aren't new, and I think documentation and tutorials are specifically to help people who aren't familiar with an existing physics engine.
Overall it covers functions fairly well in terms of core documentation, it's just examples (both live and code snippets) that would make it really useful.
Ok I'll think about what I can do here.
The other challenge I have with the API is that it's hard to find intuitively where a function might be if I just know the end result I am trying to achieve (like if I know I want to check for Bodies within the Bounds of another Body, do I look at Body, Bounds, or Engine? Answer: Look at Matter.Query).
Not sure how I can help with that except maybe some kind of search?
Again I think at this point that the biggest help would be to just write out tutorials that people can use to get started with basic applications of MatterJS.
I've added a Tutorials section to the wiki and added the tutorials I've found. If you end up writing a tutorial, I will add it!
it seems to me that the site you have would not support images, code snippets, and live examples, which is how I would see it being enhanced best
Well, yuidoc supports full markdown and html so it's possible to write these in the project source code after I've updated the documentation theme to support them. I can try look into it.
Thus the wiki is truly the best option for helping beginners get more acquainted with MatterJS.
For now I think this is the easiest route. I'm considering starting a guide section (e.g. like vue.js guide and webpack guides, which runs through the fundamentals and core modules. What do you think?
@liabru I went through one of the tutorials at https://github.com/liabru/matter-js/wiki/Tutorials.
turns out Build games with Matter.js redirects to http://www.pressreader.com/australia/net-magazine-the-voice-of-web-design/20140520/282926678418586 after a while it gets redirected to http://www.pressreader.com/
and I start seeing irrelevant news.
@imvetri I think that's just the format of the site. I saw the article upon clicking the link so it seems fine.
@liabru I think both the tutorials section and adding a guide section would be really useful. If you can outline the core modules and what those need to cover (basically what guides need writing), other people like myself can flesh them out.
If you can outline the core modules and what those need to cover (basically what guides need writing), other people like myself can flesh them out.
The most important ones are probably Engine, World, Body, Bodies, Composite, Composites, Constraint, MouseConstraint. Though I think I should probably write at least one of these to set a style and format before others get involved... for now I guess the Creating Plugins page is a good reference for the style and format I'd like to use for the guide. If you're confident already then maybe try writing for one of the modules (I guess just draft it in an md file somewhere) with that as a reference and I'll review it?
(as for examples in docs, this is some good inspiration: anime.js docs)
I've added links in the docs to search usages and examples underneath each function, property and event. See Engine.create for an example.
It's not always perfect being search based but it generally works surprisingly well for most cases, it will probably improve once the new Github search is released too.