Build Modules, Not Examples

I’ve been thinking out loud this afternoon about how modules make Node.js successful with @ekashida, YUI’s newest team member.

YUI is a powerful open-source library for developing web apps. Node and YUI both document their APIs very well. Unlike Node, we also have 250 examples to help people get started. Yet lots of people have trouble getting started anyway.

How do we make that easier?

We’re not the only web app library with this problem. Ember has received criticism around getting started and quickly responded with a roadmap to improve it. In their response, Tom Dale said:

Ember promises—and, we think, delivers—tremendous value. But ramping up to that point is not easy, and we received this feedback repeatedly and take it very seriously.

We get the same feedback for YUI. We also take it seriously and a fellow team member is working on better documentation. Ember’s action items include a Getting Started guide, a short screencast, live examples to run demo code, and other things. These are good and will help.

But then, I think about Node. Their official newbie documentation begins and ends with Hello World on their homepage. Node’s newbies do not get started with an example. They get started with npm.

Modules Are The Example

Node has effectively outsourced their examples to the community using npm.

You may be thinking: “Reid, modules are not examples. They are tools you use to build an example, or a real app.” Well, you’d be right. Node’s community has built enough modules to help people build apps they care about with a tiny learning curve. Instead of reading about code, these newbies are building something with a tool—the module—that lets them start building what they care about right away.

Few newcomers to Node.js use require("http") to build their first web app. If the barrier-to-entry was to understand the HTTP module, a lot of people would walk away. They don’t want to learn about that module, they want routing. View rendering. You know, a web app.

The example is Express. Newbies have a project in mind and it’s probably something that needs a router, view rendering, and middleware. Express delivers that. You don’t need to learn about Node yet, you learn Express.

Once you’re up and running, you have real code and real problems. Not theoretical problems in a narrative, but problems that are running on your computer. Problems getting in the way of building what you care about. That’s motivation.

Since you’ve already spent an hour getting the basics setup because the Express API was a lot easier to get started with, you’re now motivated to dig deeper into Node to find the next solution.

Building A Ramp, Not A Cliff

Understanding everything Node has to offer isn’t something you learn overnight. But that isn’t necessary. A lot of people have built modules on top of Node’s core that make all kinds of common problems easy. These modules are easy to download and use. Newbies are engaged immediately. Then, they’re are progressively lured into deeper water. The community grows.

If you need to learn a million things before you can get started, you’ll never start. If that’s your project’s learning curve, you’re presenting newbies with a cliff. Some people will climb it, some will seek climbing experts to get to the top. Some may have the patience to read a book about climbing, or watch a screencast featuring someone else climbing.

But most people want to get started today, so they’ll leave and find an alternative way to the top that’s easier to climb.

Node provides many ramps. They aren’t ramps you merely read about: they’re ramps you walk on, build on, get experience with, and get more complicated as you go up. It doesn’t fix every problem and some people will still be confused. But it works pretty well.

At YUI, I’ll be encouraging our team to focus on building example modules: the ramps to mastery. YUI is already modular, but that isn’t the same. I’m talking about bundling modules in YUI’s core into a fully-baked solution to a common problem. Other people on my team are hard at work on the first product, and now I know why I’m so excited: it’s a ramp.