So after looking at Introduction to Computational Thinking, I can’t help but think “man, I wish the documentation pages for julia packages did this instead of static websites.”
How gigantic of an undertaking would it be to revamp Julia Documentation · The Julia Language into a set of Pluto notebooks that users can actually interact with, download, run and modify?
I feel like this could also potentially simplify the way we go about doing documentation tests as well.
If I want to run some section, I just copy the section into my editor. Cloning a repo, installing Pluto, starting up a server, is a lot of work that I don’t think I would do. If the docs could be executed in the browser, that would be much lower friction. That’s what SymPy does.
looking at Introduction to Computational Thinking
That link with the Binder environment says
When running this notebook for the first time, this could take up to 15 minutes.
Which is way too much for reading docs.
I assume Mason was referring to notebooks like this: Introduction to Computational Thinking which are the object of a PlutoCon talk:
PlutoSliderServer.jl -- notebooks as interactive websites | Fons van der Plas | PlutoCon 2021 - YouTube
It would be great for docs to run in the browser, but dynamic docs shouldn’t be worse than static docs. Since static docs have the outputs visible with 0 latency, that would be good for dynamic docs too: It would even be okay for them to take a while to start up, as long as the expected output of a computation is visible during loading (retaining the zero latency).
I really like this idea and if feasible, should be done. Another feature I am/used to be incredibly fond of was the “user submitted” snippets of code on MSDN that were incredibly handy when learning about a new class/interface and how to implement it. To this end, it would be great to see user submitted snippets (that could run in an interactive notebook).
I just do not understand why use Pluto.jl instead of plain Jupyter. Pluto.jl changes how Julia code is evaluated and I really do not feel it is a good idea to add this extra layer of complexity over all the docs.
As someone who still primarily uses Jupyter kernels (through emacs org mode), I think the reactivity of Pluto notebooks has some distinct advantages for documentation material over Jupyter notebooks.
This could be an interesting Google Summer of Code project to get a MWE setup. Though it may be too late for that this year.
I think there are some packages where an “examples” notebook could make sense (when PlutoSliderServer is in a more polished state) in addition to the docs. But for a majority of docs, running a Julia server is completely overkill.
This is a (mostly) crazy idea and here is why: it makes creating docs way more work. It is already not the easiest thing in the world to do, plus it is usually pretty low priority. Adding more complexity to this process is going to give very predictable results – less documentation.
Hm, I’m not sure I see where the “way more work” comes in for package developers if appropriate tooling was created. It’d be as easy as spinning up a notebook, creating a bunch of cells that just contain
@doc f
for each f that’s documented (this can be automated too) and creating some markdown cells with explanations.
With an appropriate hosting service for the notebooks, it doesn’t need to be hard to host them either, and most of the setup for the hosting should also be amenable to automation.
In my naive eyes as someone who never bothered to spend the time to learn how Documenter.jl works, this sounds potentially easier than than using our current documentation tools, especially because the Pluto notebooks are ‘what you see is what you get’. But I am certainly open to the idea that I’m wrong about this.
There is a model of documentation that says documentation needs to fulfill four distinct roles: tutorials, explanation, how-to guides, and reference material. Here is one site talking about this idea, but there are plenty more if you search:
https://documentation.divio.com/
It seems to me that Pluto notebooks (really interactive notebooks in general) have the potential to be great for the first two categories (tutorials and explanation). The above link classifies these two modes as “useful while studying” which I think captures the fact that the notebook format is great if you plan to read something from top to bottom, but not as good if you want to quickly grep around information dense webpage.
Imagine a tutorial that walks users through benchmarking a series of functions, and demonstrates why the performance tips section of the manual is important. Or a discussion that explains how the iteration interface is implemented. On the other hand, I think that translating reference sections of the manual to Pluto won’t result in much benefit, and might actually be worse if the responsiveness suffers.
Most of you maybe familiar with Matlab’s documentation – which is great. It often has
Sometimes I wish we could have such documentation even if Julia’s documentation is very extensive and good. Now @Mason suggests
That would take the role of “LiveScripts”, which right now is missing from Julia’s documentation. I agree with that and that it would be a great feature to have.
I agree also with that. Creating self-containing interactive examples, that make sense, is laborious. But it can make learning easier and improve a user experience.
I would like to have that as a feature in order to improve documentation but I would not suggest to prescribe it as standard way for documenting. Going back to Matlab’s example: their live scripts are great for introduction and learning, but then after you have grasped the concept, you use documentation more in a standard way, as a reference and for looking things up.
As someone fairly new to Julia, and coming from Matlab, I very much agree that interactive examples are great when learning something new - and something I’ve been missing on several occasions!
I also feel that much of the Julia documentation is pretty technical and involved. I have not had the time to read the manual from start to finish, the only way I could start using Julia was to force myself to hit the ground sort-of-running, and I often find that I don’t understand a section of it quickly enough when taken in isolation.
In one of the PlutoCon talks it was mentioned how solving the two-language problem has unearthed some problems of having an unusually diverse userbase. Quite a few users are not just learning Julia, they’re also learning to program for the first time. And then my case right now, which probably resonates with many in the research community: I’m trying to use it to do computations while learning no more than needed, as quickly as possible. And many users are advanced, some very advanced: deeply knowledgeable about computer science and quite interested in the internals of it all.
A bit too often I feel like the documentation is better suited to advanced users at the cost of comprehensibility to other types of users. At the same time, I would not want to lose that information, I believe it important for the ecosystem that we provide deep information for advanced users. And when I have a bit more free time I as well aspire to understand as much as possible.
But I think there should also be a shallow version of the Julia manual, that skips over a lot and gets a new user going as fast as possible. And I think this documentation would greatly benefit from being interactive!
There are other sources to learn Julia more addressed to new users like Think Julia: How to Think Like a Computer Scientist by Ben Lauwens and Allen Downey. I think it’s a good book to start with Julia and learn to program.
It’s a testament to the quality of the docs that someone would even get the idea of learning to program by reading the documentation. It’s not supposed to be a tutorial, that’s what tutorials are for.
I’m not sure anyone has had that idea. However, one might follow the Introduction to Computational Thinking course in order to learn to program, stumble on something and try to look it up. In Matlab, that actually works (most of the time), though I doubt that there is any other programming environment where the language documentation is that good to newcomers.
Example of a quick start guide, non-interactive: Introduction to Computational Thinking
Converting the whole of the manual over to an interactive Pluto notebook site would definitely be a major undertaking. Just to put the size of the change into perspective people can have a look through https://github.com/JuliaLang/julia/pull/18588 which is where the docs were moved over from the Sphinx-based manual to using Documenter. It’s a big task.
As has already been discussed in this topic (the link to https://documentation.divio.com/ specifically is worth highlighting again) we probably wouldn’t benefit enough from a conversion of the entire thing and it would be worth systematically identifying sections of the manual that could, concretely, benefit from some level of interactivity offered by Pluto. Those sections could then be converted individually, which would be a much easier task. This can all be parallelized with enough willing contributors.
Doing the above though does raise the question of having an inconsistent visual style between different parts of the manual at that point. That’s just a case of someone porting over Pluto’s CSS to Documenter and working out an integration step that can build a Documenter site along with the Pluto pages as well in a seamless manner. Cross-referencing between the markdown pages and Pluto pages would also need implementing.
I don’t agree, at least not yet.
The core Julia docs are relatively good, many of the package docs could use more work. As pointed out, adding more work to produce docs is unlikely to produce more docs.
As a user who’s been using Julia for about 6 months, I would much rather have “how to” docs in addition to current docs than rewriting of the current docs.
For instance you could have a task “how to” visualize the Iris dataset. You’d have one example doing it with Plots. Another example would do the same task with Makie. Do the same with other “major” packages; Gadfly, VegaLite? Then a new user would look at the examples, and select which package they want to use.
These additional "how to"s could be Pluto notebooks.