undefined | Better HN

0 pointsjwilber11mo ago0 comments

"You can use as many italics as you want but I don’t think it’s a wildly bold claim and your counter example is simply silly."

I don't understand the relevance of any of this, but I think I've done a fair job outlining my points above. Let me give my best summary: the execution environment used by a library's (example) documentation is independent from learning the API of the library itself. I agree that newcomers to JavaScript may find plenty of confusion there, and I'm sure a decent chunk of D3's users may be new to web-programming in general, but it's not the job of D3 maintainers to account for that.

I actually think our back-and-forth is a perfect example of why open-source is so painful to work on.

D3 is one of the best documented libraries out there is. There are multiple books, hundreds of hours of youtube videos, and most importantly, dedicated maintainers (Mike Bostock, Philippe Riviere, etc.) who've poured hours into additional sources of documentation and are very responsive on GitHub issues.

The unfortunate outcome here is that users have come to expect this sort of high-quality support and documentation (again with the italics, who does this guy think he is???). Every D3 submodule has standard api documentation, sure, but thats expected of all libraries these days. However, the additional example documentation (again, nobody got paid to make this material) for the most recent releases has been migrated from bl.ocks.org (a now defunct open-source service users didn't pay for it) to Observable Notebooks. Now, Observable is a VC-backed business, yes, but the documentation is still completely free. In this thread, you mention you don't like this, so in at least one online conversation where D3 comes up, you actively advocate against using it out of principle! (Couldn't resist!).

Of course this is just my viewpoint on what has transpired, and I'm likely articulating it in a more-inflammatory-than-reality manner. But I'd prefer to have D3 documentation in the form of free, interactive Observable Notebooks rather than to have no documentation at all. Even more so if it helps out the authors of the open-source library.

As a tip for those who have difficulties going from the reactive Observable model to vanilla js -> you can always just take an observable notebook and ask AI to convert it to a set of vanilla files for you.

PS - Sorry for the novel, at an airport!

0 comments

infecto11mo ago

Appreciate the lengthy response, but I want to clarify a few things since I think my original point keeps getting mischaracterized.

First, the italics. You opened with “This is a very bizarre take”—emphasis on very—which, whether you intended it or not, sets a smug tone. It’s the kind of rhetorical move that shuts down discussion before it starts. I’m not saying this to nitpick style, but to point out how quickly this moved from a discussion about tooling to a dismissal of my viewpoint. It is an easy tell the person writing gives away when they use it like you do.

Now, to the substance: yes, the D3 API is technically independent of Observable. But in practice, Observable is now the primary medium through which new users encounter and learn D3. The official examples, new documentation, and most teaching material are embedded in the Observable environment, which introduces its own model of reactivity, syntax, and execution. That’s not a minor detail, it’s a real obstacle for people who just want to understand and use D3 in plain JavaScript.

Your PyTorch/mkdocs analogy completely misses the mark. Mkdocs is a static site generator. It doesn’t change the code you’re learning—Observable, on the other hand, does. You can’t meaningfully learn D3 from many of these new examples without understanding how Observable cells work. That’s a tight coupling, and one I don’t think should be hand-waved away.

“Just use AI to convert the notebook” is a non-answer. It assumes everyone is okay with outsourcing understanding to a black box just to get a usable snippet. That’s exactly the kind of indirection I’m objecting to in the first place.

Lastly, yes, I’ve set a personal boundary: I don’t want to buy into an ecosystem that made a choice I don’t support. That’s not a call to boycott, it’s just me saying, this direction doesn’t work for me. If that’s enough to dismiss my view as bizarre, then I’m not sure what kind of discussion is even possible here.

boomskats11mo ago

Entirely unrelated, but I've not heard anyone describe it as `outsourcing understanding` until now. That's a great phrase.

kowlo11mo ago

> you can always just take an observable notebook and ask AI to convert it to a set of vanilla files for you.

D3.js docs used to be fine. Now you need to "ask AI" to untangle them?

listenallyall11mo ago

> But I'd prefer to have D3 documentation in the form of free, interactive Observable Notebooks rather than to have no documentation at all

This is the core point. Yes of course the existing d3js docs are better than nothing. That isn't the complaint. The complaint is the current docs are significantly worse than older d3js docs that weren't notebook-based.

jwilberOP11mo ago

Can you provide an example? I’ve been using d3 on-and-off for almost 10 years, and the core docs have just gone from README’s to static-hosted pages with the same (version-specific) content (eg https://d3js.org/d3-selection/selecting). What is significantly worse here between the two? To my eyes, they’re basically identical: https://github.com/d3/d3-selection/tree/86

My best guess is that you’re referring to bl.ocks.org, which hosted d3 examples as standalone html examples, but this was independent from the d3 docs.

infecto11mo ago

The issue isn’t that the API documentation has disappeared, it’s that the learning experience for newcomers has degraded. The Observable-first direction has made it significantly harder for new users to grok D3 without buying into an entirely new runtime and mental model. Yes, the docs are technically still there, but they’re increasingly fragmented, and many examples now assume you’re using Observable or some variation of its reactive notebook model.

Bl.ocks.org wasn’t officially part of the D3 docs, but it played a critical role: it was the on-ramp. People learned by tweaking examples, not by reading method signatures in isolation. Saying people just want to “copy-paste” kind of misses the point, examples are how many developers build actual understanding. They’re not just blindly pasting code; they’re reverse-engineering patterns, figuring out how the pieces fit together.

We get it — you enjoy the library. But many users don’t appreciate the direction it’s taken. Such a bizarre defense. I guess we are not supposed to look at the examples when trying to grok a new library, especially a library for chart visualizations which is historically not known to be the easiest to work with.

j / k navigate · click thread line to collapse

0 pointsjwilber11mo ago0 comments

"You can use as many italics as you want but I don’t think it’s a wildly bold claim and your counter example is simply silly."

I actually think our back-and-forth is a perfect example of why open-source is so painful to work on.

PS - Sorry for the novel, at an airport!

0 comments

infecto11mo ago

Appreciate the lengthy response, but I want to clarify a few things since I think my original point keeps getting mischaracterized.

boomskats11mo ago

Entirely unrelated, but I've not heard anyone describe it as `outsourcing understanding` until now. That's a great phrase.

kowlo11mo ago

> you can always just take an observable notebook and ask AI to convert it to a set of vanilla files for you.

D3.js docs used to be fine. Now you need to "ask AI" to untangle them?

listenallyall11mo ago

> But I'd prefer to have D3 documentation in the form of free, interactive Observable Notebooks rather than to have no documentation at all

jwilberOP11mo ago

My best guess is that you’re referring to bl.ocks.org, which hosted d3 examples as standalone html examples, but this was independent from the d3 docs.

infecto11mo ago

j / k navigate · click thread line to collapse