With an increasing number of options for learning Julia—and especially the exciting announcement about the freeing of JuliaAcademy—I wonder if it’s worth having a discussion about the intended audience for any “official” learning resource. To kick this thread off, I’d like to have a discussion about the intended audience for the manual, which was started long before there were any other ways to learn Julia but may now be worth reconsidering in light of the plethora of other options.
As it is now, many chapters have a mixture of “introductory tutorial” and “reference” (a.k.a., “the complete story,” often understandable mostly by experts) material. Both clearly have their place, but sometimes I wonder if our current mix is awkward and we should move more in one direction or another, perhaps shifting some of the emphasis, splitting material to different sources, and/or becoming more deliberate in how we mix these two together.
To make this concrete, let’s start with a very simple example, the Variables page, which is the first thing readers see after “Getting started.” If I analyze the likely impact on a variety of audiences, here’s what I come up with:
- the first section starts as a tutorial understandable by virtually anyone, including someone brand-new to programming. Because it is short, I doubt an expert programmer would resent being dragged through it.
- a little ways in to the first section, we employ terms like Unicode, UTF-8, and LaTeX without defining them or linking to external resources. Fine for some readers, not for others.
- we then address “redefining built-in constants and functions”. For newbies, a small hiccup is realizing that
piandsqrtare names of other things—that is revealed after showing that you can assign to them. Conversely, an expert might wish we’d mention that if you do accidentally “overwrite”sqrt, you can “rescue” it by reassignment, i.e.,sqrt = Base.sqrt, but we don’t mention that here. - the “Allowed Variable Names” seems to start pretty clearly as reference material. It’s utterly essential that we have this information somewhere. Experienced coders will want this information now, and the full list is both useful and an excellent advertisement for Julia’s flexibility and seriousness about supporting Unicode. Newbies could perhaps benefit from a gentle introduction or perhaps don’t really need to know the full details at this point—maybe just knowing that variable names can’t start with numbers would be enough.
- later in that section we talk about “built-in” statements. That’s presented in more of a tutorial style, though again it’s short so shouldn’t cause resentment for gurus. But for a newbie, what’s the distinction between “built-in” and a constant or function as described in the previous section?
- in “Stylistic Conventions,” we refer to items (Types, Modules, functions, and macros) that have not yet been encountered. Experienced coders will agree that this is the ideal spot to summarize the rules that apply to the whole language. Newbies may wonder what all these things are and resent the growing collection of terms and concepts they don’t understand.
I did the analysis on this page because it’s short and comes early (and thus makes the analysis easy), not because it’s a particularly striking example of the tensions I documented above. A much better example might be the Types page, which has a leadoff section that might be described as best targeted at language designers, but in the fullness of time covers material relevant for everyone from newbies to highly experienced coders.
Here are some thoughts on possible directions:
- Keep it largely like it is. Many people have justifiably praised the manual, as it is well-written, erudite, and effective for many people. It may be particularly well-targeted at an audience that is also likely to be useful to Julia: people who already have some level of coding experience and who might contribute packages and the like.
- Declare that the manual is fundamentally the reference standard for the language, and streamline it for that purpose while directing newbies to other sources. Advantage: it’s essential to have a place that tells the truth and the whole truth. Disadvantage: we already have a lot of excellent tutorial material in there, and splitting it out or discarding it would be a big effort with some cost.
- Split the manual into a “getting started” tutorial followed by reference material. Advantage: newbies wouldn’t see material not intended for them, and thus won’t be confused by terms or concepts they aren’t ready to handle. Disadvantages: (1) more fractured experience for more advanced readers, particularly those who fall somewhere between “newbie” and “future core language developer”; (2) duplication of other tutorials seems like wasted effort.
- Split each chapter into material more explicitly marked as either “tutorial” or “reference” material. Perhaps color-code the section headers, if that’s technically possible. Advantage: newbies might be less bothered by terms they don’t understand if they occur in sections that are clearly marked as non-tutorial. Disadvantage: there is always some awkwardness in delaying discussion on a topic, and where do you draw the line between the two?
- Keep things woven together, but work harder to provide links and definitions for terms that might be new. Advantage: all discussion stays coherent from the standpoint of the authors. Disadvantage: newbies might be burdened with details that they really shouldn’t be worrying about at the beginning.
As you can see, I think this is a question of tradeoffs rather than an obviously-right approach. My personal favorite is probably a mix of 1, 4, and 5, slowly beefing up our “tutorial” offerings in other forums while perhaps becoming a bit more intentional about splitting chapters into introductory & advanced material.
Thoughts? I might slowly contribute to this effort, if there is some reasonable consensus about the kind of changes that should be made.
Related discussions: Some comments on the Manual