Open Source Theory

DoneJS
1

I made a video on the goals of the CanJS, StealJS, DoneJS open source efforts and how those efforts are managed. https://www.bitovi.com/blog/open-source-theory

Video: https://youtu.be/_8Sz74FsQ7M

Let me know what you think!

2

Hi Justin,

Thanks for the video, it is quite inspiring.

I work with CanJS for last 3 years, starting from version 2.2.9.
All aspects of the framework were improved a lot during this time, its really awesome. Especially I like documentation changes that done (and in-progress) during last year, since this helps with issues that I mention below. There are issues that I think valid to rise, and this thread might be good place. Of course most of them depends on community and investments, so probably they are not new, it just impossible to fix right now. Some of these issues already have proposals to fix.

Before I would like to clarify what pre-conditions I have:
Currently we have around 14 front-end developers who work with CanJS every day, sometimes Java devs tries to help wight tasks because of different reasons. So my points will be based on their experience and feedbacks from different people. Not all of points might be valid for everyone and some of them are became better this year especially.

I’ll try to split everything to different sections based on different aspects.

"Why you are using this ?"

This is the first question that people ask me on interviews, when we tell them that we use CanJS.
Our story is that year ago when we decided to write “single page application” we had requirement that it should support IE7 (and this was important, because business wanted this), so we had not so many choices: Angular dropped support of IE8, React was too new, Vue didn’t existed :smiley: , so we compared with Backbone I think and at that moment CanJS was better choice.
Nowdays state of frameworks is very different and there are top technologies that most people want to work with. Something like React / Angular / Vue. And its very hard to explain why you should start new project on CanJS, but not on something else.
This situation becomes even worse when we talk about hiring. People who only start their career want to work with “popular” technologies and market dictates them. More experienced devs who has experience with particular technologies also don’t wan’t to invest their time to something that might be not useful for them.
So I think it’s very important to explain people WHY CanJS - good framework.

Newcomers and learning

Ok, we hired newcomer to the team and he full of energy to learn something new or he is back-end developer who wants to try shiny world of front-end :slight_smile:

He starts to do something, something doesn’t work and… he doesn’t know what to do. In compare to other frameworks, you can find way less info. Worst scenario that I had is when someone said: “I can learn X framework way faster there are so many courses / articles / tutorials, why I should invest time to something else”

  • In-Depth Guide
    So we collected number of resources that we show people to help them start learning. First of them all… DoneJS In-Depth Guide. I recommend this guide, because I think this is the best tutorial that currently exist, it covers a lot from development perspective and shows how CanJS application can work, how components work with each other etc. Awesome.
    But first reaction on this is “Why I should read DoneJS ? Isn’t this different framework ?” So you need to explain that DoneJS = CanJS + “Tools” this confuse people alot at the very begging.

  • Recipes
    I think that main issue there that there are too many Recipes (Simple / Medium / Advanced)… I know that there is improvement in-progress for this section and as I got amount will be decreased. Still all of them written in different styles so its not clear what is correct approach (I’ll mention this later).
    Additional issue that sometimes they just doesn’t work :frowning: And this reasonable… because its hard to support so many recipes and update them every time. So maybe it makes sense to reduce amount of recipes, but make them really great and “production” ready.

  • Gitter / YouTube
    Then we show Gitter channel, YouTube channel, this forum. Personally for me Gitter is great place that helps me frequently, but not everyone ready to ask questions there, because this takes time to get answer and sometimes questions might be not answered.

  • Essentials
    Newest thing that helps alot is “Essentials” section. Really this helped a lot to understand what to do and how to write better CanJS even for people who worked for some time already. Currently we are using 3rd version, but still I recommend read this section from CanJS@5, because there are still approaches that can be applied in v3.

So currently documentation and information improves alot and its easier to learn CanJS than 1 or 2 years ago, but there are things that can be improved.

CanJS.com and API

Homepage
This thing is very opinionated, but I asked several people before writing this
When you open https://angular.io/ or https://reactjs.org/ these sites looks just visually more appealing and easy to understand. I don’t know about Bitovi internals, it might be that there is reason for this, but some good UX specialist can improve this, by introducing new design, rethink content of the page and its organization. It feels less “professional”, while first impression should be “wow, I want to learn this, its easy !” instead user sees tons of info.

API
This becomes better each release, plus I work with it for a long time, so its hard to find good example to illustrate what I mean, but people who just start work with is usually confused by cases like: “This is Init method. It does initialization” :smiley: It just lacks any information about how CanJS works actually. For example we have Component section, but there is no descriptions about component life-cycle or even “init” method that actually exists. And this part of issue with understanding how CanJS works in general.

Geting more info about CanJS

Lets split it on 2 options: when you work with CanJS and when you don’t work with CanJS

When you work:

For example on YouTube I found 3 channels somehow related to CanJS:
Bitovi: https://www.youtube.com/channel/UC_HPFLeKzJNLOUnLc_3311Q (310 subscribers)
DoneJS: https://www.youtube.com/channel/UCEnTQUfJi0L6l7g8IRuaVkg (83 subscribers)
CanJS: https://www.youtube.com/channel/UCM_xC8UOHt2ay5wz-3gotmg (189 subscribers)

But all of them might be useful for people who work with CanJS, but based on subscribers I think not all community aware of all these channels. Maybe it makes sense to merge them and not split like CanJS / DoneJS ? Instead its possible to create “Playlists” or Series, similar to what Google Developers have: https://www.youtube.com/user/GoogleDevelopers/playlists

There was series: “How it works”, but later next videos become random again. I think some kind of grouping may help people.

The same with Gitter channels. There are 6 channels related to Bitovi :slight_smile: (CanJS, DoneJS, Testee, StealJS, Funcunit, Trainings) maybe it makes sense to merge them as well ? Because in all of them people discuss CanJS related question. (Some channels silent for months)

When you don’t work:

Currently I don’t know any resource that advertise or shows benefit of CanJS to external audience.

For example I watched some course from Bianca Gandolfo
 (who works in Bitovi) on frontendmasters.com why not create some course about CanJS there ? As far as I know they have “training” format with live audience, so might be this is not an option, well https://egghead.io/ is quite popular as well.

I think having some “course” on 3rd party platform can help CanJS community grow. Or at least people will know that CanJS exists and it makes sense to read about it more.

"Advanced" CanJS

After you spent time to learn CanJS you can ask your-self “Am I CanJS specialist ? Am I ready to contribute there ?” And I still can’t find answer on this :slight_smile: There is no measurable point when you can think that you know CanJS. For example in Angular / React there are lots of mechanisms and internals documented, and when people want to understand level of experience in particular technology they can ask something like: “Can you explain Reconciliation mechanism in React” or “What performance optimization can be done ?”. And because these topics discussed in community or documented such knowledge way easier to get.
With CanJS there are a lot of magic happening inside that you won’t know unless you read source code. While this is an option, I don’t think this is way that many people do. I remember cases when we developed our first functionality with behaviors and tried to “find” correct sequence of behaviors that will do what we need to do :slight_smile: At that moment there was no info that position of behavior actually matters, and how they applied from first item of from last.
So after all this you can’t even say that - yes I know how CanJS.
“How it works” series is very good, but its quite hard to understand all stuff that happening there :slight_smile:

Lack of Best Practices

I think teams with a lot of developers and independent projects should feel this issue. Basically this means that you don’t know what is good way to organize things. This is not about how to use “Modlets” its clear from DoneJS (well you should know about DoneJS if you work with CanJS :D) But even with this, when you check code of Guide or different apps, or discuss how people write something on Gitter its visible that approaches might be very different, and sometimes it wasn’t obvious that this is better way to solve some issue.

Its more about how to write your code, how to organize components, what type of components you may have.
I think this proposal: https://github.com/canjs/canjs/issues/3646 can answer on this. Part of this questions might be answered in “Logic Guide”. (As I mentioned before this “new” Essentials section is very cool and helped alot)

Still CanJS not so “flexible” framework, it doesn’t make sense to not use some of its core things, like Observables, Connections, Models etc. so it feels like CanJS has concepts that people should follow to get all benefits of CanJS and they should be described somewhere.

For example other frameworks have some terms like “Compound compontents”, “Presentational components” for components, that might help with component organization and make your application more scalable. Some other concepts how to mange state, use Streams, organize data flow.
Vue has even separate section for some stuff: https://vuejs.org/v2/style-guide/ React has different parts like “Concepts” or https://reactjs.org/docs/higher-order-components.html
A lot of such stuff also applicable to CanJS, what I personally found for myself is that Angular best practices works quite well for our code base, and our applications looks very similar to how Angular apps structured.

Oh, this is quite long message I wrote :smiley: Not all of this directly directed to Open Source Theory, but still might be useful. Anyway thanks for your that you did CanJS really became better each release ! :slight_smile:

Best regards

1 Like
3

Thank you so much for writing all this up?

Do you think you could help me create some proposals based around this feedback? I think the following seem the most important:

  • Improve the homepage design and give a definitive reason to use CanJS
  • Create a “CanJS” version of the in-depth guide and emphasize that.
  • Consolidate youtube and gitter channels
  • Create a best practices / architecture guide

I’m a bit confused what to propose from the “Advanced CanJS” section. Would continue to add “how it works” sections to our docs help?

Here are some examples:

Regarding:

There is no measurable point when you can think that you know CanJS

I think providing someone this might be rather hard as CanJS has become so abstract over the years. To understand how can-define’s observability works, you need to know:

  • How to satisfy canReflect.getKeyValue() with the can.onKeyValue symbol
  • Working with can-queues to dispatch elements.
  • Working with can-observation-recorder to work with computed properties.

Those “how it works” videos were my attempt at answering this question. But even once someone understands how the observables work, then to be really an expert, they will have to know stache. The core things about stache:

  • can-view-target - the “compile target” of stache
  • can-view-parser - an HTML parser
  • can-view-nodelist - organizes the stache hierarchy
  • can-view-live - Able to keep part of the dom up to date with an observable
  • can-view-scope - the scope lookup construct of can-stache
  • can-stache - Includes a parser for expressions. Then uses both can-view-parser and its own expression parser to generate functions that result in a renderer.

I guess I see people can become experts, but I think it’s easier to become experts first at one part (observables) and/or another part (stache/view)

I’m not sure how to go about solving this problem …

The only thing I can think of is to continue making “how it works” sections on these technologies, and then maybe a “how it works” section for “all” of CanJS.

Anyhoo … thanks again for your feedback. We take it super seriously. I’ll be thinking about it a lot.

4

In terms of why someone should use CanJS, I’ve been thinking of stating that it’s probably the easist way of writing CRUD apps. As CRUD pages are 90% of what most people do, I think this might be appealing. I’m curious what you think.

Here’s some of the “evidence”:

CanJS handles promises (with their state and errors) REALLY well

{{# if( todosPromise.isPending) }}
 Loading
{{/ if }}
{{# if( todosPromise.isResolved) }}
  {{# for( todo in todosPromise.value }}
   ...
  {{/ for }}
{{/ if }}
{{# if( todosPromise.isRejected) }}
  {{todosPromise.reason.message }}
{{/ if }}

In react, you’d have to make sure the promise is hooked up to call setState with the resolved/rejected value and have a whole bunch of boilerplate.

The models make it easy to handle all those other weird edge cases

As models have a .isSaving() and .isDestroying() method, it’s easy to disable a button like:

<button disabled:from="todo.isSaving()">Create</button>

It handles updating lists when items are added/removed/destroyed automatically

We call this automatic list management. When a “todo” or other record is created, updated, or destroyed, you don’t have to update the lists on your page. This works with pagination, filtering, sorting.

Here’s an example:

5

I wonder if we should just drop the DoneJS moniker. It might help CanJS, since it’s the most popular of our tools anyways, if people think they get all of the tools included with it. It would help with documentation too, if there were a Tools section on canjs.com. Some of the donejs libraries are only documented in their readme which makes it hard to find the right documentation when working on a donejs app.

6

Hi Guys,

Thanks for your super-fast response, didn’t expected that this brings so much attention.
I’ll to answer on some points from your replies.

Proposals.

There is proposal that covers this part I think:

So maybe we can just add more description or add reference to this thread there ?

Created:

Created:

There is such proposal, maybe we can just extend it with Architecture:

“Advanced” CanJS

Yes I think “How it works” sections and videos definitely great stuff and It will be great if you continue with them.
I think they can solve one part of this. Maybe it can be improved by some graphic / diagrams that presents information. Idea is that this is nice to have “verbal” explanation of how things works. I think React’s documentation is quite good in this term: https://reactjs.org/docs/optimizing-performance.html#shouldcomponentupdate-in-action
( Well React has less API that they need to explain of course :frowning: )

Additional point here is that there is different goals that people may want to achieve:

  • Some people need to implement small application fast that “just works” and fast.
  • Others need to implement long-living apps that has good performance, scalable, maintainable etc.

Second result requires way more knowledge in how framework works, because writing something that “just works” not enough. This requires understanding of how to write CanJS better, how to split layers, how to split components, how to avoid / solve / improve performance (so you need to understand very clear what can affect this).

CanJS expertise

Yes, I agree that CanJS contains different parts that you need to learn and understand. So this point actually about all these things :slight_smile:

You see, many packages that you mentioned above never used directly. We wrote around… 3-5 applications and never used directly something like can-view-scope because this is internals of can-stache so in general you won’t even click this page in API documentation. As result you have can-stache that actually used in code and lots of packages that works under the hood, but rarely used directly. Still you need to learn them and know about.

Yes “How it works” videos can be good place to cover them.

Why CanJS great.

Yes, I actually agree with you, when I passed through DoneJS guide after CanJS 2.2.9 it was like a magic :D.

Maybe, but you need to learn how to think in “CanJS way” first.
I remember that dev from another team who had no previous experience with CanJS came to me one day and said:

“I just want send GET request to this URL why its so hard in CanJS ? I don’t need model, I just want to get data.”

So… in general I know that CanJS can do good things, and it possible to be quite productive when you develop using this framework. But there is should be a way to explain this to others :smiley:

Well this is quite global decision, doubt that I can say something here :slight_smile: A lot of effort was putted to DoneJS, so it depends on how gracefully this can be moved to CanJS.

Best regards.