Having many forms is valuable, but I’m a bit skeptical that you can make very clean divisions like this. Some love doing tutorials to the end before starting, others only learn by trying to solve a real problem, often without yet knowing the tools properly. (Or having forgotten half the maths they should probably know.)
Better links to resources other than the manual seems great, as suggested above. But each probably does have to aim at several purposes.
Likewise, I think quick documentation available at the REPL is very valuable. Especially with examples illustrating quirks / alternatives / related features. This seems like the easy place for incremental improvements. No need for everyone to agree a grand plan, anyone can just pick some functions and start.
For the existing docstring structure, the obvious candidate is UnicodePlots. Someone could try a few and see how they look, then make a PR to discuss.
Including plots as SVG or something would be a bigger change, as these probably couldn’t be shown at the REP. At present the website always (I think) has the same documentation for a function as the REPL help.
This is an idea I was hoping we’d get to. If the experts on this forum cannot figure out the right package to use to plot a sine wave, how can beginners figure it out? Why force the beginner to make choices they don’t understand, before they ever even make their first plot?
It’s not that “the experts can’t figure it out”, it’s that all of those generally do the same thing, with a different “flavor” of code. Which package people choose is a matter of taste. Endorsing any of those interfaces/packages by including it in a language-level reference/tutorial/documentation that is not only about plotting is an arbitrary choice that could be just as well served by any other. Matlab doesn’t have this problem because Matlab comes with plotting included, which julia does not.
This doesn’t instill much confidence in the Julia language. If the fear is that some future change in Plots.jl might eventually cause an error in a simple example, what does that mean for my code, which is likely to be much more complex than plotting a sine wave? Must I live in perpetual fear that any day I wake up might be the last day my code ever works?
Being afraid to “endorse” any particular plotting package may feel like a safe approach, but really what’s happening is we’re passing that fear onto the user, and making it their responsibility to deal with.
I see the question pop up every now and then why there’s not just a single plotting package in Julia, because Matlab fares well with that model. The reason is that Matlab is a language plus GUI product with inbuilt plotting, Julia is just a general purpose language, so any GUI / plotting functionality must be added by packages. Why not pick one “best” package and be done with it? I have spent a lot of time on Makie and I think one can make pretty good plots with it. It has advantages over other plotting solutions, but also disadvantages. Some of those can be solved with time and effort and some are just design choices. So while I would obviously be devastated if people said “Forget Makie, Plots is the only sanctioned plotting tool now”, it also doesn’t make any sense to say “Forget Plots, only Makie” because Makie cannot serve every user’s needs all at once.
Being afraid to “endorse” any particular plotting package may feel like a safe approach, but really what’s happening is we’re passing that fear onto the user, and making it their responsibility to deal with.
Who should endorse a package like that? The core contributor team? Not all of them even do plotting, how could they make a choice like that. Julia is not a company that needs to focus its product line, its a collaborative open-source effort of hundreds or thousands of people. So figuring out the “right” packages can only happen over time, not with top-down decisions. Of course that can make it harder to compete with commercial / company-driven solutions like Matlab or RStudio/ggplot, but that can’t be avoided I’m afraid.
I think the focus now is too much on plotting. I don’t think there need to be any plots in the documentation at all. Note that very few functions actually make sense to plot. (How would you plot searchsorted(x) or threadid()?) If a user wants to find out how to plot a sine function they probably will Google “plotting in Julia” and find everything they need. I don’t think a user will look at the documentation of the sine function to find out how to plot it (at least I wouldn’t).
I do agree that it would be very beneficial for new users to have the documentation separated in a tutorial and a reference section. The reference would essentially be the current docs, describing formally every function and feature of the language. The tutorial would contain a much less technical description of common code patterns with lots of examples. The Python documentation makes this distinction very clearly.
the related issue: Diversity
~Our community has very different backgrounds ( academic, IT, Julia in programming )
novice
advanced beginner
competent
proficient
expert
~ and not everyone is perfect in English → Localization.
"Julia’s official documentation is in English, but many groups work to translate and localize documentation and other resources. "
and We have a declaration from the Diversity
"We believe that maintaining and promoting diversity and inclusion is the only way we can have a strong and vibrant community. "
Theoretical question: How we can maintain and promote these ideas (D&I) in the Documentation?
( ~ “dogfooding” )
maybe we can extend with languages codes?
( REFERENCE:es , EXPLANATION:es , TUTORIALS:es )
// “es” = Spanish language code
or We can invent a better documentation idea?
Right now, the Julia documentation has mashed together a bunch of HOW-TO (Getting started, Performance tips, Workflow tips), REFERENCE (most of the manual), EXPLANATIONS (Developer documentation, bits and pieces all over the place, for instance metaprogramming), and the odd fragment of one kind of docs interspersed in another kind throughout.
I don’t mind at this stage: I have learned enough to be able to make sense of most of it, but initially I was most grateful when someone could put some sense into it in this forum. (I still am, in fact.)
But: I think at this point it would be worthwhile to start separating out the different kinds of docs, mainly in the interest of making it really easy for newbies to get up to speed.
Then give it a serious try, if for some reason the tools you ate using now are not quite satisfactory for you. Don’t let superficial or partial evaluations make your mind.
In terms of tooling: I am low hanging fruit (I don’t think I have ever inspected a function in Python and wouldn’t even know what to do). And my debugging are print statements.
I think the blog post did not mention the REPL. But I would never ever develop code in a REPL.
Now you will ask me why the uproar? But Julia adoption will come through people who know what they are doing and this often means professional developers (and they are more likely to expect tooling features proper).
But what would interest me: parallel computing out of the box and Julia (allegedly) has been playing with Lisp in the same sandbox when they were kids.
But kind of I am really shocked (what would have happened to me) and glad at the same time that I haven’t made the transition to Julia 10 years ago. It would have meant: 10 years of what Sisyphus did back then 2500 years ago and a lot of suffering and disappointment.
[Btw: if you ask me: Python (and especially numpy) is the worst mess that has been thrown to us humans.]
Ten years ago was the very first version of Julia. If you chose Julia at that point you would be a very early adopter. If you truly considered, not playing with the language, but transitioning to it, then I am sorry but that one is completely on you, not on Julia. For any language that behaviour would be extremely reckless and unwise.
(Glad where I work they banned us from using IDL and a few IDL licenses have been kept for legacy code but no one is allowed to develop IDL code. IDL was the worst thing ever invented).
On our (the real big ones) super computers we wouldn’t be allowed to do data analysis (by this I mean post processing and plotting). But Python can be used for general tasks and computations.