🏠 back to Observable

thoughts from someone who liked using bl.ocks to learn D3

Hi Observable maintainers,

Thanks for building such a great framework.

As an old bl.ocks user to learn D3, however, I found it a bit hard to get used to how observable works, especially at the beginning. Now every D3 example is linked to Observable, so as I try to get used to it, I found that I miss some things bl.ocks provided. Let me describe them in detail.

First, I liked how easy it was in bl.ocks to open a standalone web page that only contains the completed visualization and use the browser console to inspect elements and fiddle things. With Observable, I was hoping such an “open” button could exist as well.

Second, the code in bl.ocks was in the order they are executed, whereas in Observable it’s often the other way around. I found it really confusing to see a completed visualizations on the top but have to read code from bottom up. What’s more frustrating is that sometimes bottom up is not a linear order either. If cell A references cell B, there is no guarantee that A will appear before B (or the other way around). This possibly can be alleviated by providing a “go-to-cell” functionality (if I click on a referenced cell B in A, the page jumps to cell B). But I suspect that’s still not ideal for people who are used to read code in linear order.

In general, I feel it’ll be great if there could be a link to the bl.ocks counterpart of a D3 example, if there is one.

1 Like

I partially disagree with the post arguments personally

First, I liked how easy it was in bl.ocks to open a standalone web page that only contains the completed visualization and use the browser console to inspect elements and fiddle things. With Observable, I was hoping such an “open” button could exist as well.

Observable consists of multi-cell blocks and “open” button exist at the left side of every cell. Fiddling things is much easier on Observable than on bl.ocks

Second, the code in bl.ocks was in the order they are executed, whereas in Observable it’s often the other way around. I found it really confusing to see a completed visualizations on the top but have to read code from bottom up. What’s more frustrating is that sometimes bottom up is not a linear order either. If cell A references cell B, there is no guarantee that A will appear before B (or the other way around). This possibly can be alleviated by providing a “go-to-cell” functionality (if I click on a referenced cell B in A, the page jumps to cell B). But I suspect that’s still not ideal for people who are used to read code in linear order.

Yeah, I kinda agree with you in that, sometimes you don’t know from where to start notebook exploration and it’s pretty hard to find starter cell when code blocks are being hidden. But that very much is the author’s responsibility I think, you can put everything in one cell if you want linear order

Actually, “go-to-cell” functionality is a very good Idea (ctrl+click on referenced cell ), but as you mentioned is not ideal for your problem

The best side of using Observable is breaking down of things and the possibility to fiddle them independently.

I was kind of pessimistic when I started using this platform, but it turned to be great for everything

  • Exploring things. (visualizations mostly)
  • Learning new js libraries and techniques
  • Using it for the fast exploration of the topics (references svg dropshadow, svg strokeDashArray)

I feel like it accelerated learning and working process. Observable lets you explore things much more deeply than you could in web-based editors

My advice - spend some time on Observable, play with things, once you’ll see it’s advantages, you won’t be willing to go back

3 Likes

There’s some related discussion in this thread: I want to learn D3. I don`t want to learn Observable. Is that ok?

1 Like

The open button on Bl.ocks I was referring to opens another weg page that contains only the visualization. That web page allows me to very easily inspect elements – which is super important IMO to new learners. Right now, I don’t find such functionality on Observable. Inspecting elements is impossibly hard.

I totally agree. I was just describing things that are missing – reading, inspecting a vis as a whole, like what bl.ocks provided.

Thanks, I found it as well after I posted. That post was mainly meaningless rant. Hopefully I helped point out things that are blockers for people like me.

You should be able to access the iFrame that your notebook content is rendered into using the dev tools. Unfortunately, the cells are not accessible from the console by default, but you should still be able to access the DOM.

That is a good feature request though — since there’s already safe mode which only shows the code, maybe there should be a similar mode which only shows the output.

1 Like

You should be able to use your browser’s element inspector as normal by right-clicking on any element and clicking Inspect. Is that not working for you?

1 Like

thanks, that works. I guess in the first few tries I was clicking on some blank area, and somehow the browser brought me to other page elements.

Personally I find that Observable (a) makes reading [well-written] code examples much easier, and (b) makes writing them dramatically easier.

The non-linearity (with excel-style reactive updates) that you are having some trouble with is the most import part of that.

In a regular repl, Mathematica or Jupyter notebook, bl.ocks, or plain code file, everything executes linearly from top to bottom (or in whatever order explicit subroutines call each-other). This is almost never the clearest logical order for explanation. If something up top makes no sense without the context of something down below, that’s just too bad (at best, there might be separate documentation or a comment saying “go read here first”).

As an author of a typical code file, if you change something, you need to re-execute the whole lot to make sure you aren’t stuck in an inconsistent state. This makes the feedback loop much slower.

In an Observable notebook (and in “literate programming” the order of code follows the author’s desired narrative structure. If what the author is communicating is relevant to the reader, the reader more-or-less matches the intended audience, and the author writes clearly and structures their argument well, then this is vastly more effective.

The caveat is that if what you are interested in learning is different than what the author is interested in communicating, then the advantage somewhat goes away, and you are left reading in whatever order you need to answer your own questions. (But being able to freely open/close and re-order the cells and open a notebook in multiple windows with the content synchronized can help readers a lot.)

I recommend practicing with it a little. If you spend a few days or weeks with it, I am guessing you will come to appreciate the trade-offs.

Yes, the power that non-linear order possesses goes without saying – I already feelin it after fiddling with some notebooks.

I’ll try a few more days, but my strong suspicion right now is that a non-linear order is perfect for fiddling and communicating stories but not necessarily for new learners to understand code. As a D3 learner, I’m very used to reading the code in their order of execution to get a general idea of how things flow. I believe I’m not an exception.

Without a linear order, I strongly feel that a functionality that lets you quickly identify a referenced cell, either “show value on hover” or “jump on click”, would be very useful.

A linear counterpart of a notebook, which I don’t think it’s hard to generate (as long as the reference graph is a DAG?), would be helpful for understanding purposes for sure, and may also be helpful in cases like copying/pasting code into other environments.

One thing that can help is to see the graph. Try pasting a notebook’s link into https://observablehq.com/@mbostock/notebook-visualizer

For example, https://observablehq.com/@mbostock/notebook-visualizer?id=@jrus/munsell-spin

Feature request: It might be useful to someday make this a built-in feature to show an alternate view of a notebook as a clickable graph, where clicking the nodes would show their code and output.

1 Like

I’d argue that it depends on how that nonlinearity is applied. I try to create segments of cells in my notebooks according to their relevance, each with its distinct heading:

  1. Very brief intro and main visual demo at the top
  2. Tweakable nobs (i.e. options object or form widgets) - if applicable
  3. Notebook’s primary API (i.e. cells suitable for imports) and/or helpers (depending on the notebook content)
  4. Dependencies (external libraries or notebooks required by the API)
  5. Demo dependencies and helpers (stuff that’s only needed to showcase the concept)

The idea is a quick onboarding, followed by an invitation for some playful interaction to get the concept and/or techniques across. After that a deeper dive into the underlying code can then be done more selectively, even without a dependency graph.

I’d love to discuss some of the existing d3 documentation notebooks to get an idea of everyone’s perspective. The following questions could act as a framework to make opinions comparable:

  • What was my intent/expectation when I opened the notebook (also: where did I get the link from)?
  • Was I able to obtain the information that I was looking for?
  • How well could I navigate the notebook? What helped, what interfered?
  • Did I have to change the default cell states often (view hidden sources, hide large expanded sources)? Would I have expected them to be different?
  • Was the code reasonably easy to follow? If not, what proved difficult, what would have helped?

Answering these might give insight into the different ways in which notebooks are read. Ultimately we might even be able to distill a style guide that notebook authors can follow.

4 Likes