# More CanJS documentation remarks

**URL:** <https://forums.bitovi.com/t/more-canjs-documentation-remarks/893>\
**Category:** CanJS\
**Created:** [May 25, 2018, 5:15pm UTC](https://forums.bitovi.com/t/more-canjs-documentation-remarks/893 "2018-05-25T17:15:01Z")\
**Posts on this page:** 2\
**Page:** 1

<div class="post-metadata">

**Author:** ![code-read](https://yyz1.discourse-cdn.com/flex035/user_avatar/forums.bitovi.com/code-read/32/111_2.png) [@code-read](https://forums.bitovi.com/u/code-read)\
**Post date:** [May 25, 2018, 5:15pm UTC](https://forums.bitovi.com/t/more-canjs-documentation-remarks/893/1 "2018-05-25T17:15:01Z")

</div>

My [previous remarks about DoneJS documentation](https://forums.bitovi.com/t/canjs-documentation-questions/889) 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](https://canjs.github.io/next/index.html):

Today I was attempting to understand this code[\*](#notes) in an example from the [5.0.0.pre.0 API doc on can-component documentation](https://canjs.github.io/next/doc/can-component.html):

```
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](https://forums.bitovi.com/t/canjs-documentation-questions/889)). Then I searched for **_DefineMap_** and landed on [this page about Map](https://canjs.github.io/next/doc/can-connect/can/map/map._Map.html), which gave the terse description:

> Specify the type of the [DefineMap](https://canjs.github.io/next/doc/can-define/map/map.html) that should be instantiated by the connection.

That explanation wasn’t sufficient so I clicked on the word [DefineMap](https://canjs.github.io/next/doc/can-define/map/map.html) contained in it, which caused [this page describing can-define/map/map](https://canjs.github.io/next/doc/can-define/map/map.html) to appear. The beginning of the page reads,

> ## `new DefineMap([props])`
> 
> The `can-define/map/map` module exports the `DefineMap` constructor function.
> 
> Calling `new DefineMap(props)` creates a new instance of DefineMap or an extended DefineMap. Then, assigns every property on `props` to 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](https://canjs.github.io/next/doc/can-connect/can/map/map.html). 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](https://canjs.github.io/next/doc/guides/technology-overview.html#Key_ValueObservables), under [Technology Overview](https://canjs.github.io/next/doc/guides/technology-overview.html). 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](https://canjs.github.io/next/doc/can-define/map/map.html) should link to [Key-Value Observables](https://canjs.github.io/next/doc/guides/technology-overview.html#Key_ValueObservables) 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.

---

<div class="post-metadata">

**Author:** ![chasen](https://yyz1.discourse-cdn.com/flex035/user_avatar/forums.bitovi.com/chasen/32/402_2.png) [@chasen](https://forums.bitovi.com/u/chasen)\
**Post date:** [May 25, 2018, 6:24pm UTC](https://forums.bitovi.com/t/more-canjs-documentation-remarks/893/2 "2018-05-25T18:24:18Z")

</div>

@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](https://github.com/canjs/canjs/issues/4057) 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](http://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](https://github.com/canjs/canjs/issues/4154), 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](https://github.com/canjs/canjs/issues/4155).

[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](https://canjs.com/doc/guides/advanced-setup.html), 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](https://github.com/canjs/canjs/issues/4116) (that was one of the most highly-voted items in our [last community survey](https://forums.bitovi.com/t/donejs-contributors-meeting-2018-04-27-survey-results/871)).

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](https://canjs.com/doc/guides/chat.html) and [TodoMVC](https://canjs.com/doc/guides/todomvc.html) guides, then looking through the different [recipes](https://canjs.com/doc/guides/recipes.html). If you’re more of a “read the API docs” kind of guy, then the [can-define/map/](https://canjs.com/doc/can-define/map/map.html) (and [PropDefinition](https://canjs.com/doc/can-define.types.propDefinition.html)) docs will get you started with observables, the [can-stache](https://canjs.com/doc/can-stache.html) docs will get you started with templates, and the [can-component](https://canjs.com/doc/can-component.html) (and especially [ViewModel](https://canjs.com/doc/can-component.prototype.ViewModel) docs will help tie those together. 😃