I notice in many notebooks by @mbostock and many others, that the charts are drawn at the top while the variables and functions used to create it are defined at the bottom. The purpose of this seems to be to keep the focus on the simulation/visualization rather than the code used to generate it. But it does make it hard to understand the code if the reader’s interest is to better understand how the chart/simulation was generated.
I love this project but I would like to know if new users (programmers) who come here for understanding the code (used to generate visualizations) have a hard time understanding the code primarily due to it’s structure.
Are there any particular recommendations for structuring the code or does it all depend on the use case? If I am writing a tutorial for a viz, it makes sense to define and explain my variables at the top and gradually build the visualization. But if the sole purpose is to create an interactive essay to teach a concept then variables can hide away at the bottom with visualization and it’s explanation at the top.
You ask about recommendations for structuring the code. Since there’s no semantic difference to the ordering of Observable cells, it all depends on the use case.
If you’re showing off a graphic, and the code is the details, putting it at the bottom — or even in an Appendix — is quite nice.
On the other hand, if you’re writing a tutorial, building up your visualization piece by piece, with Markdown paragraphs interspersed to explain what you’re doing, is a lovely way to go.
Finally, your question points at the need for us to write more introductory notebooks in other styles, and from other points of view: “I’m coming from <script> tags. What’s going on here?”. “I’m used to Jupyter notebooks. What is this thing?”
Yeah, that’s what i thought was the implied reasoning in structuring the code in the way it’s structured here for most visualizations.
This is all I needed to hear! I feel a lot of us are coming from that background which brings in some confusion. If you dig enough here, it’s clear that this is potentially more useful and fun than Jupyter notebooks but seeing that quickly isn’t easy and superficially it can look more complex than in actuality.