My previous remarks about DoneJS documentation were so well received I’m encouraged to share a bit more 
. Note that all of the following is based on the 5.0.0.pre.0 docs:
Today I was attempting to understand this code* in an example from the 5.0.0.pre.0 API doc on can-component documentation:
var ViewModel = DefineMap.extend({
// Contains a list of all panel scopes within the
// tabs element.
panels: {
Default: PanelList.extend({})
},
active: {
Type: Panel
},
...
So I performed a CanJS native search for the term DefineMap.extend and found nothing (search issue already covered in my previous post). Then I searched for DefineMap and landed on this page about Map, which gave the terse description:
Specify the type of the DefineMap that should be instantiated by the connection.
That explanation wasn’t sufficient so I clicked on the word DefineMap contained in it, which caused this page describing can-define/map/map to appear. The beginning of the page reads,
new DefineMap([props])The
can-define/map/mapmodule exports theDefineMapconstructor function.Calling
new DefineMap(props)creates a new instance of DefineMap or an extended DefineMap. Then, assigns every property onpropsto the new instance. If props are passed that are not defined already, those property definitions are created. If the instance should be sealed, it is sealed.
I’m sure this makes sense as a reference to those already versed in DefineMap, but it’s not helpful to me as it uses terms I don’t yet understand (including DefineMap!). The rest of this page isn’t much better; the most general explanation I found was,
can-define/map/map is used to create easily extensible observable types with well defined behavior.
But I don’t know what easily extensible observable type or well defined behavior mean and am also puzzled that DefineMap is apparently being referred to as can-define/map/map.
Following another result from my above search, I read the can/map documentation. It is a bit more generalized and useful, but still doesn’t answer my original question, What is DefineMap?
By browsing the CanJS documentation site I eventually discovered the section Key-Value Observables, under Technology Overview. Here, I find a generalized explanation which if I read it enough times I think I will finally understand, and which in turn will serve as a key to the rest of the CanJS documentation.
But the Technology Overview doesn’t come up when I use the CanJS documentation page’s search for DefineMap! I would argue that it should, and that the words observable objects at the top of the can-define/map/map page should link to Key-Value Observables in the crucial Technology Overview document. That would quickly direct newbies like me to this vital information (and stop us from bugging you so you can spend more time coding!)
*BTW, for me the code creates an Add vegetables button that doesn’t do anything. I assume the example is still “beta” and am trying to make it work as an exercise.
I have an 
]
️]