Feedback on the documentation and learning resources

[amsaid1989]

I don't know if I am the only one who has experienced this, but as a newcomer to D3, I found that pairing D3 with Observable for the learning material a bit confusing.

Observable, of course, is an amazing resource in itself, and I think it works really well for testing D3 and presenting examples. But I found that, for me as someone just starting with D3, Observable has added an extra layer of complexity that I would have preferred to avoid at this early stage.

It might just be that this is my first time using Observable and that, with time, things will start to click. But I think that makes it a little bit harder for newcomers like me.

Do you think it could be beneficial to have an introduction to the library that doesn't rely on Observable?

[curran]

You may like https://vizhub.com/create-viz

Also I'm doing a new educational series Get it Right in Black & White where it's vanilla JS and D3.

[amsaid1989]

Those look brilliant, @curran. Thank you very much. I will check them out.

[curran]

Thanks!

There is a larger question here as well, I think, which is - Can/should the official D3 documentation have a few examples, or an official introduction to the library, that is vanilla JS?

[amsaid1989]

I personally think this is necessary. A lot of people using D3 would probably looking to use that on their websites, so they will probably be using it with vanilla JS.

This would also help newcomers like me avoid having to wrap their heads around Observable which is a bit of a departure from what a lot of people would be used to when coding.

I still maintain that Observable is a brilliant platform for testing, practicing and presentation once you get comfortable with D3. But it is a bit much for newbies like me.

[curran]

Thanks for your thoughts on this. I totally agree.

[robertmaxes]

i think it's worse than this. If you come looking to learn D3, you get a website that has nice examples and a few tutorials, that are not maintained and typically refer to older versions. There are several documents explaining version changes, and then you get passed to Observable when you start looking for more up to date examples.

And, honestly, it has all the same issues - inconsistent documentation, multiple versions, and of course the variant framework of Observable. And if you consider embedding Observables as the base toolset, you will face this startling admission on Embedding an Observable :

along the way, our documentation and support has grown haphazardly, through responses to forum posts, leaving behind a trail of examples and warnings you have to stumble upon and bookmark for later. Many of those problems remain unsolved, but we are either working to fix them or working to document the workarounds that have been floating around the community, and collect them in places you are more likely to see them.
(quoting https://observablehq.com/@observablehq/embeds )

No doubt there is enthusiastic technical innovation going on but it's remarkably difficult to find a current set of best practice examples and sound tutorials to scaffold learning for those who don't already know where the version issues and workarounds actually are.