Hatching a Visualization

Building visualizations with D3.js can be a haphazard process. In this article I’ll talk about different ways to start new projects, and some of the challenges that are likely to crop up along the way.

How do you start a new project in D3?

There is a wealth of tutorials available for D3. These are good learning tools and worthwhile reading for anyone learning the fundamentals of D3. However, once you’re more experienced with D3, a tutorial won’t be of much value unless you find one that closely matches the project you have in mind.

As an experienced D3-er, you’ll probably have the API reference handy. But do you code everything from scratch?

I—and most programmers I’ve asked—use an example or a previous project as a starting point. Even a simple-looking visualization has a lot of moving parts, and examples can provide many things:

Because examples are often instrumental in getting a new project up and running, the abundance of freely usable examples is one of D3’s greatest strengths.

Anatomy of a project

A visualization built with D3 uses the basic elements of the web: a sprinkling of HTML and CSS, and a significant chunk of JS to tie it all together.

Many D3 examples are hosted on services like bl.ocks.org, JSFiddle, or CodePen. These services store and present all the necessary code, making it easy to preview and dissect, clone and customize.

If you’re lucky, you can grab some example code, change a few labels and colors, and drop in your own data. Presto, you just made a working visualization!

But maybe you need data in another format, or with additional variables. Or you want to reorganize a chart, or render things differently, or add some new interactivity or animation.

The situation can get out of control quickly. Most examples don’t provide much in the way of documentation or comments, and D3 code—even well-crafted code—is typically a tangle of terse, vaguely-named functions and closures. (I’ll explore this claim in a future article about refactoring well-known D3 examples.)

If an example proves to be difficult to adapt, you’re no longer building a shiny new visualization; instead, you’re elbows-deep in an autopsy of someone else’s code.

Charting libraries

One way to avoid the pitfalls of inscrutable example code is to adopt a charting library.

With minimal coding, you should be able to create standard charts (bars, lines, pies, that sort of thing). You can pile on extra visual flair and annotations, and enable complex (but again, standard) interactions. And all this probably comes with decent documentation as well.

Charting libraries built on top of D3 include NVD3 and C3.js. It is also worth considering popular JS charting libraries that do not use D3, such as Google Charts and Highcharts.

If a particular library meets all your needs, it can be a quick out-of-the-box solution, and you can focus on higher level issues in your project.

Despite all this convenience, I rarely reach for a JS charting library. This is because my needs are either so minimal that a whole library would be overkill, or I need to customize my visualization to a degree where the library ultimately hinders progress more than it helps.

Also, in programs with complex structures and many moving parts, I vastly prefer code over configuration.

Although I don’t tend to use them myself, I think JS charting libraries are great examples of usability for developers. Wouldn’t it be nice if more D3 examples had thorough documentation, or were designed for adaptation and customization?

Murky beginnings

Whether I’m working on a D3 project, configuring a ready-made chart, or otherwise drawing something with SVG or Canvas, I always look for an example first. But where are all the good ones? Where to look first?

  1. Check if Mike Bostock created a relevant example—he did write D3, after all, and his examples (unsurprisingly) use the API better than most.

  2. Root around on D3’s Gallery for anything that sounds promising.

  3. Search for relevant examples on blogs, and check Blocksplorer or CodePen for a more focused search.

  4. Keep digging, but settle on a more generic starting point: anything simple that will get you up and running.

This process leaves me feeling lost and a little bit crazy: I can’t possibly be the first person to attempt a particular visualization, but searches can be fruitless. I often find only scraps of an answer in the form of undocumented example code, static images, and sometimes academic papers.

Fuzziest practices

Are people not sharing their visualizations?

Why are the visualizations that do get shared so difficult to discover?

Is there any way to encourage quality comments or documentation alongside examples?

Why is there no online market (that I’m aware of) for unique JS visualizations? Is that market owned by charting libraries?

What is a good boilerplate for new projects? Is the new standard for plugins useful for creating self-contained projects?

Beyond packaging, what coding standards should a project follow for things like user interaction?

So I’m still trying to figure it out: how do you start a new project in D3?