Pitfalls for beginners and the value of convenience and hand-holding

#1

I am soon going to try and give a Julia tutorial in my research group (cognitive neuroscience). It will be for people mostly acquainted with Matlab and R, maybe a few people with some Python experience. I’m therefore thinking a lot about angles from which to show Julia which might appeal to non-programmers. I think there’s real value in Julia for my colleagues, but at the same time I’m already building a mental model of all the pitfalls and problems that we’re going to encounter in a tutorial, and how I can have the experience not be overshadowed by them.

Personally, I’ve gotten used to many of these quirks and their workarounds, but I wonder what can be improved here. What I find especially interesting is how much the language explains itself to the user when errors appear. I would call any of such measures “hand-holding” because that’s what beginners need and it’s also what more experienced users don’t worry about.

One example (maybe not a very good one but you’ll get the gist):

When trying to redefine a struct MyStruct you get this error:

"invalid redefinition of constant MyStruct"

So for a beginner who’s poking around in the language, trying to test out a few things, does this explain what’s going on? Are we dealing with a redefinition that has invalid content? If so, why? Or is it invalid to redefine it in the first place? Why constant when I wrote struct?

A hand-holding version could be:

"""
Tried to redefine MyStruct.
Changing the definition of an existing struct is not allowed for performance reasons.
For details check http://julialang.org/some-page-with-explanations
"""

Obviously this can’t be done for all error messages, but maybe for the top problems that people struggle with when they learn the language? I can imagine that many people here feel this is unnecessarily verbose and should be obvious once you read the documentation. I’d argue that it’s exactly this kind of hand-holding that makes a language like R and the tidyverse so popular. It’s not raw performance that attracts people but the overall image that they get, the ease of use. And I’d argue any effort spent on beginners is worth it, because they turn into users or contributors. Contributors bring new packages and users bring funding eventually. (I sometimes see the argument that people who really have no skills in programming are maybe wrong here and should stick to R or Python, but that’s exactly how you get so many people trained in these competitor languages from an early level).

So I was hoping for others to chime in and list instances where basic things in the language could be made more beginner friendly. A pro can always ignore a longer error message, but if it’s too short or vague the beginner gets stuck.

19 Likes
#2

I think the biggest pitfall is assuming that you do not need to read the manual (just the manual, not the standard libs or devdocs) from beginning to end before using the language.

But in fact, every new user should do this. One does not have to remember everything, just have a vague memory of something being mentioned so it can be revisited later.

Like the FAQ item that anwers this exact question.

9 Likes
#3

I think this is a great idea. Error messages are typically written by experts but read by beginners, which can make conveying the right kind of information challenging. The best way to make this happen is probably to open PRs to improve error messages as we come across them.

6 Likes
#4

Come on. If you’re going to spend your life developing julia code, why not. Otherwise, just no. I never read a single manual from beginning to end, and pretty much nobody else does this.

In this case, the error message is technically correct but very low-level and confusing to new users. @jules I feel your suggestion is too verbose and beginner-oriented, but there could be a middle ground, like “Invalid redefinition of existing struct MyStruct”. Same probably also goes for const a=1; a = 1.0. If you could make a list of error messages you find confusing and open an issue/PR with that, I think it could be very helpful!

27 Likes
#5

Just to reiterate, the specific example I gave was not that important to me, just something I came up with while thinking about the classic errors people make. So I thought, why not try to help as much as possible when errors appear. Nobody in my tutorial will read the official documentation I am sure, the same way they’ve never once read python R or Matlab documentation. All beginners do is execute other people’s scripts and maybe look up help for specific functions, and then maybe try a couple of things themselves. If too many things get in the way of that they are just likely to get frustrated. And again, I don’t think we should take that lightly as a community because resources are diverted to where the users are, even if they’re just doing “basic” stuff. I would love to get as many beginners motivated and on board as possible.

And this is not constrained to error messages, any kind of thing we can do to make things easier for people exploring the language is important. Like this other post I made about better tab completions when working with dataframes for example RFC: Tab completions that are sensitive to already specified function arguments (inspired by what R offers in that regard)

3 Likes
#6

I consider myself one of the rare people who reads manuals. I’ll often read the manual for a product before it arrives at my door. I’ve read significant chunks of the Julia manual over the last year but I definitely haven’t made it through. It now stands at 107 chapters and 1276 pages. I don’t believe it is realistic to expect one to make it through the manual before seriously using Julia.

8 Likes
#7

I think we should run a “hundred paper cut project” like what Ubuntu used to do (https://en.wikipedia.org/wiki/Paper_cut_bug). Unfortunately, that takes people who have time and knowledge, and those tend to be mutually exclusive. Maybe we could divide up labor between people who report usability bugs (that don’t need to, and in fact shouldn’t, be julia experts), people who discuss what should be done (which tend to be less critical, as there is usually no shortage of opinions for usability decisions) and people who implement the solutions (who know their way around the code, but might not have the energy to report and discuss bugs)

7 Likes
#8

The term “paper cut” is great, that’s what these things are like.

#9

Just to clarify in case it wasn’t clear: I am talking about the part from “Getting Started” to “Noteworthy Differences from other Languages”. That’s about 400 pages in the PDF. About 200 of which can be skipped on first reading (handling OS variation, calling C and Fortran, etc).

I am genuinely puzzled how people expect to learn a new language without reading something equivalent. It may be a book on Julia, but the manual is high quality, up to date, and available for free.

I fully support making error messages more friendly. But there is only so much you can do without some context. Without some overview, the user will be facing a very complex puzzle that is very frustrating to figure out by bits and pieces.

2 Likes
#10

Oh definitely, you can’t expect to learn Julia well without reading documentation. I don’t think this issue is about learning it really well. But I definitely think that Julia right now has a lot of “unofficial workflow requirements” that exist to circumvent limitations, are just conceptually different than in Python or R for reasons that newcomers don’t immediately understand, or that people have just gotten used to. Like the Revise workflow, having to load Statistics before you can run some basic function like mean or other basic functionality “hidden” in non-base packages, having to restart Julia in many instances and then waiting for recompilation again. (I feel quite well versed in the better workflows and I still have to do that way too often, especially when developing with Makie which likes to crash every once in a while, and this happens much more often for inexperienced people). So I think it’s an important goal to make things easier for beginners, keep them away from most of these problems, at least when they start out. I don’t have the magic recipe for how to do that but getting a discussion going is one way to “raise awareness”.

7 Likes
#11

That is correct, but a lot of them are addressed in

https://docs.julialang.org/en/v1/manual/workflow-tips/

If you think that this part of the manual could be improved, please consider making a PR.

I think that this discussion exemplifies a difference in how people approach learning a new language. I usually try to find a good intro book about it, which for Julia happens to coincide with the manual. I would then proceed to work through this book with the computer in front of me — I would say that for Julia, this would take a day or two. This is a significant up-front cost, but it saves a lot of time later on.

Apparently some people prefer a more experimental approach, would like to dive into the language, and prefer to be told about things when they come up.

To the extent this is possible, I think this is a great idea — error messages should be informative and helpful. I am just skeptical about how far one can take this, because the computer is not very good at guessing what part of the context is missing for the user.

1 Like
#12

For the specific point of improving error messages the error message catalogue repository was created to collect error-messages that can be improved.
It could use some contributions.

7 Likes
#13

Hi Tamas,

I’m sorry for the snark in my reply. You’re a very helpful member of this community and whatever minor difference of opinion we might have regarding reading of manuals is not worth arguing, or to put it another way, I think we agree much more than we disagree.

Cheers.

4 Likes
#14

No worries, I don’t mind people disagreeing with me. But thanks for writing anyway!

4 Likes
#15

As a beginner who has only built VBA and SPSS scripts since learning Fortran and Basic way back when, these are the things that confused me. RTFM did not work in many cases, so a quick job became a lengthy information search. The manuals assume a reasonable working knowledge of the specifics of the language and don’t always make matters more clear.
This is not intended as a beat-up. It’s just input about possible difficulties experienced by people new to Julia.
Anyway, here’s the list:

  1. The whole business of paths specific to Linux taken as a given without a side note that Windows paths are different. Occasional examples of Windows paths would help.
  2. How to change a var type.
  3. Heaven knows why a single column of CSV data opens with readdlm as Type{Float64,2}
  4. The difference between {Float64,1} and {Float64,2} is only explained by an example that fails to express what the difference is.
  5. Pkg documentation could mention how to access pkg> using ] and how to exit it.
    Generally finding and loading packages was never the challenge. The challenge came in interpreting the documentation about what variables to pass and sometimes the package documentation was less than clear on the issue, especially with optional parameters.
    Life with Julia has got easier since I got Intro to Python training :wink:
#16

You may have misunderstood something here, there is no such type.

Here, context is missing: these may be type parameters of something, probably an Array. I would recommend

https://docs.julialang.org/en/v1/manual/types/#Parametric-Types-1

#17

Thank you, Tamas. Yes, Arrays. Apologies for the inaccuracy.

To a beginner user working solo, the implementation of Types is confusing and error messages owing to Type mismatch can be frequent. Since explicit Types are at the core of Julia it’s an issue I suggest will cause beginners grief, particularly if they are used to looser environments. So Types should be covered in any introductory tutorial. I’m not talking about composite types or abstract ones, but just about working with primitive types and ensuring the type matches function requirements. Personally this was an area that cause me a lot of distress, despite hours trying to understand the manual.

#18

As @Tamas_Papp would in all likelihood point out soon there’s a great opportunity here for you to help - the manual is open source and editable on GitHub, so if you found any of the examples misleading or unhelpful (you mention the Array{T,1} vs Array{T,2} case) feel free to make a PR with an improvement!

2 Likes
#19

I think the main problem is that working with parametric types and multiple dispatch is inherently difficult to learn. Many powerful things are. Prior experience with programming contemporary languages (and I am not including CL/CLOS and Dylan here) does not help much because Julia is pretty unique.

I don’t think there is a shortcut here: documentation and tutorials can be improved to a certain extent, but the subject matter requires careful study, revisiting concepts multiple times, and trying them out in practice.

FWIW, I don’t think that presenting a subset of what the manual says on this (basically the Types and Methods chapters) in an introductory tutorial is possible, as it is inherently connected.

Not really, see the above. I think the manual is close to being optimal. (I am sure you meant well, but there is no need for you to guess what someone else would say on a topic, they can just write it themselves).

1 Like
#20

As I noted earlier, the original post is not intended to be a beat-up, but rather a note of difficulties for a beginner. I have no problem being part of a solution, but consider it presumptuous to suggest changes to documentation, given my misunderstanding is probably due to my own shortcomings. The forums here and elsewhere are helpful in clearing up such issues.

1 Like