Total reading time: 3:57min (based on Alex)

When you try to learn a new programming language or work with a new framework for the first time you’re likely to google something along the lines of “How to …” or “framework X tutorial”. As a developer you might also be the one writing how-to articles for your own creations. If you’re interested in turning your 569-page long, textbook-style manual in to a golden asset of yours, please read on.

Your 20th century, worn out screencast series isn’t that fancy either…

Some users just get started with programming or using a framework (or whatever your product might be). Not everybody is a pro. For the rest of us tutorials are a low-barrier entry to your creation.
Furthermore, thinking about tutorials early on will force you to avoid complexity. For example, if you can’t explain a concept in simple terms, you should probably think about it again. By putting yourself in the shoes of your prospective customer you help yourself to create a better product in the end.

So how should an amazing tutorial look?

The idea behind most tutorials is to show the reader a step by step protocol of how you, the developer, would do it. However, what the user really wants is to learn, not to watch the presenter using his evil vim skills to confuse the overwhelmed newbie who is busy trying to get off the ground. One would learn way faster if she was live coding and seeing the results as she writes the code herself.
I’d love to see more editors in the browser used for this purpose. For example, the codecademy uses an in browser editor and console to teach programming to beginners.

How to use multi media the right way

Screencasts are a popular tool when it comes to tutorials. However, they are not interactive, so the user can only watch but not try for herself unless she pauses the video and switches to a text editor, checks the results and repeats. Also, you can’t copy and paste from a screencast. We can do better.
Video can transport emotions. So I think it should be used for just that. How about a short introduction to the topic one is about to tackle? Just ten seconds of someone talking to you “face-to-face” make the whole experience more personal. Audio can do a great job at communicating a lot of content without requiring a lot of screen estate. Carrying on with the last example, the person who gives the introduction should also be the speaker of the tutorial. Additionally, text can help with copy & paste issues, hyperlinking to other resources such as the documentation, etc.

Positive feedback loops vs. frustration

Most tutorials that I encountered where quite frustrating. The reason being that there was no positive feedback loop supporting my will to learn more. For example, I never knew how long it will take to complete a certain tutorial. This sometimes leads to me not even starting because it gives me a psychological excuse.

“I probably won’t be able to complete it before lunch, anyways.”

vs.

“Ah nice! This is going to be done before lunch.”

So, in your tutorials please tell the user how much time she has to invest. As this forces you to think about the structure and length of your lessons, your whole tutorial will benefit.

The khan academy does a great job at keeping its students motivated with occasional achievement badges. People want to be rewarded when they take the effort to learn something new. Tutorials are a tool for just that. So please treat it like learning. Progress can be rewarded constantly for example with points or a virtual currency that one earns. I think we can learn a lot from games in regard to how they keep people engaged.

If you have some good examples, please let me know in the comments.

Summary

In the end the user is the reason for your creation, product or project. Thinking about your tutorials early on is a good way to ensure you’re producing something of value. Because your users are the ones who will ask you questions about your project, will buy your products (if they are for sale), submit pull-requests and talk about your creation in public, a great set of tutorials will benefit you the most.

tl;dr
Don’t spend your budget on a social media campaign run by an evil marketing firm. Spend it on your tutorials. It’s the best marketing there is.

Resources:
codecademy: Nice editor in the browser. Positive feedback loop.
khan academy: Eleborate achievement system. Also, nice for improving your general knowledge.
knockoutJS: Editor in the browser, progress saved in localStorage and it can fix your code.
Try Haskell: Interactive console for learning/trying Haskell.
Layer Styles: Play around with the parameters and get an intuitive feeling for the css behind it. That’s the power of live editing.

Modules

AMD stands for “Asynchronous Module Definition”. So, what are modules? I’ll quote the definition from the CommonJS Module specification, as it describes it very well:

This specification addresses how modules should be written in order to be interoperable among a class of module systems that can be both client and server side, secure or insecure, implemented today or supported by future systems with syntax extensions. These modules are offered privacy of their top scope, facility for importing singleton objects from other modules, and exporting their own API.

So, modules are isolated parts of code that live in their own scope and are kind of self-contained. Well, that is pretty much how we see the individual Features in EmbedJS – we made our feature implementations as small as possible and reduced dependencies as much as possible. Many of EmbedJS’ features are also browser-independent, so why not make it possible to use some of the tools in a non-browser environment?

(If you want to learn more on modules and why we need them, I recommend @briancavalier‘s presentation on modules.)

Features in EmbedJS

So far, I didn’t really explain what I mean with “Features”, so let me do another quote, this time from the Project Page:

EmbedJS uses the concept of features: Functionalities are split up into features, as fine-grained as possible, and each feature might have multiple implementations.

Our Features are kinda small and contain only few methods, sometimes even just one. The asyc-promise feature, for example, will get you Promises, and the transport-jsonp feature will get you a method for pull in data via jsonp – and that’s it.  If multiple methods are contained within one feature, this is because they are too closely related to each other to split them up, like the html-class feature, which contains the addClass, removeClass, toggleClass and hasClass methods.

AMD vs CommonJS Modules 1.1

Now that we knew modules were the way to go, there was another, quite important question to solve: There are two common patterns for modules, so which one do we want to apply? One pattern is described in the above mentioned CommonJS Wiki, the other pattern is described in the AMD wiki.

Well, there have been some blog posts lately that compare the pros and cons of each of them, so I don’t want to repeat all of this – but I’m hiving a similar tendency towards AMD. Besides this, there was another big reason to go with AMD: Remember, EmbedJS is based on the Dojo Toolkit, and it’s a Dojo Foundation Project – and we hope that the efforts that went into making EmbedJS might flow back into the Dojo Toolkit one day. And as the Dojo Toolkit uses the AMD approach, the decision was quickly made to do so as well.

Implications for EmbedJS

There are several huge benefits for EmbedJS in using the AMD approach. The most noteworthy surely is the ease-of-use for developers. In your code, when you find you want an EmbedJS method, you look up the feature name that provides this method, add it to the require statement and there you go. Man, easy.

A second important thing is that EmbedJS now plays really nice with AMD based projects. In fact, you could see EmbedJS now as a collection of small useful modules, that can be easily integrated – and also easily extended.

The third major benefit is that we can now get rid of all the custom tools we built around EmbedJS – you can load features with any AMD loader (though we use and recommend RequireJS) and build it with any AMD optimizer/builder (we recommend r.js).

Let’s have an extra word on

Building

It was always possible with EmbedJS to create a custom build that would contain only the features you wanted/needed in your project. But, you had to use our build tool that we created. And learning & using Yet-Another-Build-Tool™ is always… well, let’s just say it would be cool to avoid it (and, not to forget, so is maintaining it). We did a lot to improve that, we created a GUI that allowed you to just “click together” the features you wanted, and we worked on a dynamic loader that would ease development. But still, the situation was far from ideal, and people just ended up going for our ready-made “kitchensink” builds that contained all of the features.

Now, we still provide those ready-made builds that contain only the implementations for a given platform (and are stripped of require/define calls), but I really hope that using the AMD approach and using an AMD optimizer to deploy will become the more adopted style.

Q: Cross-target? A: The Feature Plugin

One goal of EmbedJS is to allow for easy cross-device development. We got rid of run-time branching but instead went for an approach that held the different implementations for a given feature in separate files, so that one only has to deploy the actually needed code to a given device – and not all the alternate implementations, that sit useless in the device’s memory and never get used. We needed to achieve that with “in-house” means provided by the AMD approach. Lucky us, there’s the concept of loader-plugins, and so I created a feature-plugin for AMD loaders. The idea is simple yet effective: You create an implementation map that maps a feature name to an implementation, and if there are multiple implementations, you supply tests that tells the plugin which feature to use.

When you’re ready to deploy, you have two choices: I f you really don’t know on what target your code is going to end up, you can use the dynamic implementation map containing the tests for the optimizer, and you’ll get a build that contains all of the available implementations. Then, during runtime, the feature plugin will run the tests and load the specific implementation. But, if you do know what target your code will run on, you provide a specific implementation map that doesn’t contain tests but directly maps to the according implementations, and you will only have those in your built file.

Synopsis

AMD is exactly what we needed to make EmbedJS more what we want it to be – an easy to use JavaScript toolbox that is especially handy for cross-target scenarios such as cross-platform mobile development. So, please don’t hesitate and check it out on Github, read the project page and check out the examples!

Resources / Further Reading

• EmbedJS on GitHub
• EmbedJS Project Page
• EmbedJS API Docs
• AMD-Feature plugin
• AMD Wiki
• CommonJS Wiki

If I can’t debug, for whatever reason and have to fall back to console.log()s you normally see my code looking like this:

You can see two things here:

• the first line prints out a variable’s value, simple I guess
• all console.log()s are not indented at all

Let me touch on the “not indenting” first.
I don’t like to indent console.log()s because this just makes the code look ugly, and that is intentional, because console.log() normally just doesn’t belong in the code. By making the code look ugly I am quickly forced to remove them again, the latest I will stumble on it before committing, because I never commit without looking at the diff.
If I ever forget to remove the console.log() I can be sure that a coworker will be annoyed by it and hopefully either ping me or remove it. But I am trying my best not to forget it :).

Komodo macro

Back to the first console.log() you see in the code example up there, that one is actually one keystroke away for me, I have hacked a simple macro in my editor (Komodo Edit) that takes the text I selected and creates a console.log() in the line below throwing out this variable and it’s value.
This little script looks like this:

Just create a new macro with it and attach a key-combination to it and logging a variable is just one key stroke away.

Recently the new WAC 2.0 Spec got out and it’s looking good.
Compared to WAC 1.0, the WAC 2.0 Spec is a shift into the right direction:
Instead of inventing new APIs, WAC 2.0 adheres to web standards like HTML5 and W3C Widget Packaging.

Let’s compare the two major spec revisions in that repsect:

As said before, the WAC 1.0 Spec described distinct APIs, e.g., for audio, messaging (SMS & email), camera and geo-location.

Taking photos, for example, involved assigning a callback to a global value inside the Camera object and invoking Camera’s captureImage method.

There’s a problem with that: What if two pieces of code both assign their own callback to that shared value?
The one which assigned its callback last will be executed. The first callback is “dead code”.
Of course this can be remedied by the app developer, but I believe it’s the library’s job to get something as essential as deferred execution right.
All WAC 1.0 APIs use this global callback model and inherit the problem.
There are better, more elegant ways to defer execution (e.g. dojo’s Deferred or node’s callback passing & EventEmitter).
And fortunately, WAC 2.0 replaced the old model with a callback passing approach.

If everything goes well, what could WAC provide developers with?

1. An easy way to package web apps “for home screens & app stores” by wrapping web apps in native container apps.
2. An extension of browsers’ capabilities to enable richer web apps. This includes APIs for camera and file access.
3. In contrast to alternatives WAC has a strong focus on carrier network APIs. This could enable purchase through carrier billing.
4. A security model to effectively protect user’s privacy and security.

So go ahead and look at what the new WAC 2.0 has to offer.
I’m excited to build apps with it once it’s running on some major platforms!

To conclude I’d like to end this post with my personal opinion on what I believe WAC needs to focus on to succeed:

1. WAC runtimes have to run at least on iOS, Android and a few other major-marketshare platforms. There’s no point in developing cross-platform web apps if you ignore major platforms.
2. WAC’s marketing & identity need to be more developer-centric. Different top-notch WAC runtimes need to be advertised by WAC. Ideally there would be an official runtime for each platform.
3. Apps built on top of WAC runtimes have to be compatible to major app stores. For example, imagine a developer is targeting Android and iOS. What if Apple rejected WAC-based apps because of, e.g., a bundled custom WebKit build? I’m pretty sure no sane developer would consider WAC if that effectively banned their app from ever going into the most profitable app store. And while there will be carrier-operated stores I am not overly confident in that. Human beings simply prefer one familiar store/market on their phone.
4. Web app developers want their code base functioning consistently across multiple platforms with little or no effort. This implies that different WAC runtimes should strictly respect the specification. If there are implementation differences it’ll result in multiple code branches in the app code to repair broken implementations. Well, if WAC wants to succeed this must not become an issue for the app developer! Most apps are going to need custom code to support physical device differences. So hey, it will be incredibly helpful if the basic APIs were consistently implemented! Please don’t screw this up, because I somehow doubt someone would develop a cross-WAC-platform JavaScript framework.
5. WAC 2.0 runtimes with the above properties should appear very soon. They also need to be advertised in an easy to understand manner.
6. WAC should stick to W3C specs & drafts for APIs. If an API becomes part of a given platform it should be removed from that platform’s WAC runtime. Think back to when Google removed Gears support from their own browser to make way for standardized APIs.

What is it?

It‘s a JavaScript Toolkit, especially aimed at embedded devices. Embedded devices, that is phones, tablet devices, TVs, car dashboards and the like. Devices that are capable of running JavaScript. We are sure that this list is going to grow over time – and will hopefully one day also include devices like your fridge. EmbedJS is based on the Dojo Toolkit.

Why?

Because the toolkits and frameworks that exist focus on desktop browsers and therefore have a different approach – an approach we didn‘t find that suitable for embedded/mobile development. And the JS frameworks that target mobile devices are flawed, too: either they target only a specific device or platform, or they provide far more than we do need and want.

What we wanted was a toolkit that offered a unified API across different platforms, but with the best implementation that was available for each platform. And we didn‘t want to ship code that implemented a certain feature for, say, an old Blackberry device to an iPhone. Plus, we wanted that API to be small – enough to assist us in our daily work, but not that bloated that we would ship code to a phone that we wouldn‘t need in most of our projects.

The Dojo Toolkit

We at uxebu have a strong affinity to the Dojo Toolkit – most of us are committers – for a good reason: we believe that it has done many things right, and that it has an excellent code quality. Thus, finding a starting point for our venture to what was later to be EmbedJS was pretty easy: It was the very core of the Dojo Toolkit, dojo._base.

We examined the code and split it into its smallest parts (features, how we call them in EmbedJS). After having the features all nicely separated, we could look for the best implementation for each of the platforms we wanted to support, and put it into a separate file. Then we optimized our code, tweaking here and there, but also using the code from dojo._base as it was, because it already was the best implementation.

And we needed to find means to put all these tiny parts together again, respecting any given dependecies, to create a file that then contained all the feature‘s implementations for a given platform – so the EmbedJS Tools were born, including our highly flexible build system.

API

EmbedJS‘ API is a small subset on Dojo‘s API. It provides around 70 methods, from the fields language enhancement (like Array manipulation or JSON), OO (like classes and inheritance), transport (like JSONP or XHR), event system (like connecting to DOM events or methods), DOM manipulation (like style or node creation) and misc things like Promises or pub/sub.

We kept the method signatures intact so that you can import your existing knowledge from working with the Dojo Toolkit to EmbedJS. There are only a few minor changes where we
a) found a new name highly useful, e.g dojo.io.script.get() is embed.jsonp()
b) we needed to strip given functionality for the sake of code size.

All methods in EmbedJS are available under the embed namespace as well as under the dojo namespace. I.e. to call the connect method you can use dojo.connect() and embed.connect().

The full API documentations is here, though it‘s undergoing some updates right now.

Summary

I didn‘t want to dig too deep in the first article on EmbedJS, but I guess you got the point: EmbedJS is a highly optimized Dojo core, and offers you a specialized, optimal build for a given platform. To explain how the build system works, how we manage dependencies, how we separate our features and our implementations and how one can create a project-oriented custom build will need another blog post – but if you are too curious, you are invited to take a look at the source code at github; a lot is self-explenatory there. A further source of information is the EmbedJS project page, as well as the EmbedJS Tools source.

First I want to thank RIM for sending us two Torch devices. Right away I navigated to the embedJS tests and I didn’t expect it differently, the tests passed without any problem, 100% passed tests. Actually I expected the tests to pass lightning fast, the time it took was ok, but not lightning fast, unfortunately. The test suite executed in about 14 seconds, on the iPhone4 it took about 10. To be fair the processor power and the system architectures are completely different and not really comparable, but the user experience counts in the end. We have heard that the RIM guys are hard working on improvements and speeding up the device, there is some cool stuff to come.

WebKit and WebWorks

The most impressive and revolutionary thing was definitely that BlackBerry brings an 100 points ACID compliant WebKit and runs W3C widgets using it. So there are by default two ways that are even fun to get content onto this platform. You can write mobile websites expecting an a-grade browser and you can write apps, for the so called WebWorks platform (which are W3C widgets inside). All we want. The browser supports CSS transitions and transforms, not 3D though, since there is no GPU in those devices, but you never know what might come next. There is SVG on it, WebSockets, Canvas and a lot more niceties, I just browsed the objects using Object Browser, go try it yourself, on your device.
RIM renamed their widgets that existed already on BlackBerry5 to “WebWorks” and they got completely overhauled. The approach RIM went is pretty close to how PhoneGap works. WebWorks basically is a wrapper written in Java (the native language of BlackBerry) which internally instanciates a WebKit view and provides a bridge into JavaScript where the underlying native functionality is written in Java, of course. The cool thing about it is that this code is completely open source and on github. Unfortunately the build scripts are still not on github, so you would still have to figure out yourself how to use the source from github to package your apps. RIM please push them soon! Currently the executables are the most comfortable way to build your widget.
Back to the API, since the implementation is open source you can easily extend it and make functionality available into JavaScript which currently is not there. So Nikolai’s robotic JavaScript will really become fun and reality on BlackBerry too. Why RIM went this way becomes very obvious when you understand the security concept on BlackBerry. Since all APIs are, in the end, provided by a Java implementation and only “piped” into JavaScript all security restrictions apply to the widget just as if it was a native app. That means if you access GPS in your widget (using JavaScript) the Java function will be called and will be secured the same way as if it would have been called from within a pure Java app. Of course this doesn’t make your widget secure by default, since you are using web technologies you have to take care of writing apps which are not vulnerable by XSS attacs or alike. But it offers really comfortable extendability for this platform and is no workaround to get web technologies onto BlackBerries, I think it’s a very clever approach, good job RIM.

Security

Everybody knows the ridiculous installation dialogs on Android which show you the APIs the app wants to access and the final question if you want to allow the app to access this functionality or not. If you say “no”, the app won’t install. That doesn’t really make me feel that the security concept is very flexible. It’s not giving the user a lot of control. Working with Opera’s widget runtimes already for a while I thought of a concept that would allow a lot kore control for the user and make apps hopefully more successful.
I will use a short example to explain it. Imagine a twitter app that you want to install and that has a lot of functionality but on the first install you only want it to be able to go online to read and send tweets. Functionality like GPS, searching my addressbook or taking pictures with the camera are built in into the app. But as long as i don’t trust the app i don’t want this functionality enabled. So I turn of access to certain APIs upon installation and enable them just when I feel secure and gained trust in the app or had been told by experts that the app is secure. But this is currently not possible on platforms like Android or iPhone. I talked about this idea and told RIM’s Tim Neil about it, in the hope to meet open ears and confirm that this is a good idea. The answer I got surprised me big time: BlackBerry already has this for a while. We got out our Torch devices to look it up, and yes in the menu under “Device / Application Management” you can edit the permissions per app (see picture). Awesome and just right, I love this.
So Opera this was my idea to improve your widget runtime and maybe to jump ahead of the crowd again, I would like it.

Overall the BlackBerry6 platform is very exciting and a lot of thought seem to have gone into it, especially with focus on the web, which is a really good thing. So, I will just step away and try to build the Object Browser as a WebWorks App.