@code-read, thank you so much for taking the time to write this up! It is very very appreciated and absolutely not a bother!
You’re right that the descriptions of the main packages aren’t that great; for can-define/map/
in particular, that description doesn’t give you much info at all. I have an issue open for that, and your suggestion to link to other docs is a good one.
[BTW, not saying you have to do this, but I want to point out: on each canjs.com page there’s an Edit on GitHub link, which makes it easier to submit pull requests to fix things in the docs. If you were so inclined as to submit a PR to add a link in that description, we’d get it merged in, otherwise I will later today. ]
Also, thanks for pointing out that broken tabs demo, I think I can get that fixed today.
One way we’re going to fix some of the issues you brought up is by updating all the package titles to their more common name in CanJS 5.
[For some backstory… in CanJS 3 & 4 we encourage everyone to use the individual packages, like can-define
. This is more difficult to get started with, so we added a module that exports the packages by the name we commonly use in the docs, e.g. import DefineMap from "can/es"
instead of import DefineMap from "can-define/map/map"
. This’ll be the default in CanJS 5, so we’ll update the site to show those names instead (which I think would solve the issue of not being able to search for DefineMap and get the right docs). The More You Know.™ ️]
After we get CanJS 5 out the door, we’re going to turn our attention towards fixing a bunch of things in the docs (that was one of the most highly-voted items in our last community survey).
One more thing in this lengthy post… some more resources to help you get started: if you haven’t already, I’d recommend checking out the Chat and TodoMVC guides, then looking through the different recipes. If you’re more of a “read the API docs” kind of guy, then the can-define/map/ (and PropDefinition) docs will get you started with observables, the can-stache docs will get you started with templates, and the can-component (and especially ViewModel docs will help tie those together.