D3: Finding examples for D3 v4 is difficult

[AndrewRayCode]

I'm brand new to D3 and wanted to share my experiences as a newcomer.

It seems like D3 v4 is lacking documentation and examples to help developers understand the library. In my case I searched for "d3 directed graph" and found http://bl.ocks.org/d3noob/5141278, which I copied the code for into a local project, and used the latest version of d3 from npm. After facing many Javascript errors and not knowing why, I found out all of the most helpful example I've seen seem to be using the older version of the API.

I tried looking for an equivalent graph in d3 v4 but so far I've come up empty handed. The documentation on forceSimulation is fairly nightmarish to a newcomer, with no actual examples of how to use the code. Beginners in new libraries often copy examples and then tweak values to see what does what, an excellent learning experience. If the first interaction with a library is trying to decipher cryptic API changes, without knowing anything about the old nor new API, then the opportunity for learning is hindered.

I'm sure this is a growing pain of any library, but I think some community work could improve the experience for newcomers. Updating examples, improving search ranking of newer APIs, etc.

[mbostock]

Thanks for the feedback, and I’m sorry for the frustration. I do make an effort to link to examples from the API documentation, and I have even given talks on this subject; see For Example. The d3-force README links to a number of practical examples (see the images) which are probably the best starting point for learning the API. That said, there are not many examples for the individual API methods.

An unfortunate consequence of maintaining thousands of examples (and dozens of repositories) is that it will be a while before I am able to update all of them to v4. It would also be a tremendous amount of work to add practical examples for hundreds of individual methods in D3’s API. I am very sorry that you had a nightmarish experience, but keeping the examples up-to-date is just one part of my overall effort for making visualization easier; I am balancing multiple strategies concurrently.

Prior versions of D3 have existed for five years, so it’s not surprising that they outnumber v4 examples in search results. I expect that more newer examples will exist over time. If you want to contribute, please make new examples and open pull requests in the appropriate repository to link to them from the API Reference. Or consider publishing and sharing a tutorial. Thank you!

[curran]

Here's a search utility built by @enjalot that helps finding D3 examples that are using V4 http://blockbuilder.org/search#d3version=v4

Within this tool, you can search for any keywords in combination with the version, for example, here's the search results for "directed graph" with version 4

[yoonghm]

That is great!

[abrahamdu]

I really appreciate your information above as well.

[ericucsc]

Thanks curran!