Blog post about my experiences with Julia

I cannot recall saying I had specific issue(s) with that package’s docs. I made some effort to describe where my experiences matched the OP’s, and I even provided a couple of examples of the issues I had - none had anything to do with the said package (which I never used) and its docs, so I’m bit puzzled by this request.

Also, this seems like a nice insight into what developers vs. newbies are frustrated about when it comes to the docs and the feedback.

1 Like

Mostly Docs.

1 Like

It’s not supposed to be faster to type functions (at runtime, you will get the same code assembly code, do you know of exceptions? maybe it’s faster at compiling, not sure). It is can help to put types in your structs.

1 Like

The cases where it’s helpful to add type information can be found in the Performance Tips. Otherwise, adding unnecessary type annotations can make your code less flexible without any significant performance gains.

5 Likes

I haven’t gotten to the DiffEq package or explored its docs, but I totally understand what @MK-1138 is saying here, if we’re talking about the base documentation:

There’s an important concept in communication, which is show, don’t tell. Julia docs do some telling, but essentially no showing, whatsoever. That makes it hard to learn.

As one example, take a look at the docs for the sin function. The documentation tells users that sin computes the sine of x, where x is in radians, and then says nothing else. The documentation just ends there.

  • What should a user do if their x is in degrees and not radians? Actionable item: Include a note that says, “If x is in degrees, use sind”, and hyperlink to sind.
  • What if x is complex? Help users understand how sin computes complex numbers, so they may develop an intuition for the function and have a way to verify that they are using it correctly. Actionable item: Take inspiration from the MATLAB docs for sin , and explicitly show users how to compute sin.([-im pi+pi*im/2 -1+im*4]).
  • Most importantly: Where’s an example that shows how to calculate and plot a sine wave? This is the first thing many beginners will try to do, and already, they’re stranded, expected to know how to define a range of x values, expected to know to include a . in the sin call to calculate the sine over multiple values, and expected to know how to create a plot. Actionable item: Include an example that shows how to calculate and plot a sine wave.

I think many of the points @MK-1138 articulates are related to a pervasive issue that the documentation was not written for the people who will need to read it. Rather, the docs tend to come across as shorthand notes that devs made to themselves. Actionable item: Include examples with context in the docs for every function, starting with the simplest use case for each function, and then include gradually more complicated examples if warranted, to give users an intuition for how to turn the knobs of each function. MATLAB’s documentation for plot does a nice job of displaying the range of its possible use cases.

The apparent lack of awareness of who will be reading the docs, and what they will need to learn from them, applies equally to Julia’s error messages, which are sometimes a jumble of cryptic sentence fragments that may leave users wondering how to put all the fragments together into a complete thought. Actionable item: Write all error messages as complete sentences following this formula, in this order:

  1. Identify the location of the problem. (e.g., Error on Line 5 in rationalize():...)
  2. Describe the technical cause of the problem (in human language).
  3. Conclude with some gentle advice for what can be done about the problem.

I’ve just recently begun my Julia journey, and I totally understand the confusion that many new users experience, often as a result of not having clear guidance on how to do simple things (like calculate a sinusoid) or not knowing what the error messages mean when mistakes are inevitably made. I suspect that many of the perennial issues that beginners struggle with and post about on this forum might vanish with more thorough documentation and clearer error messages.

25 Likes

Yes! Thank you!

I’m glad that you too mention MATLAB as an example for how to write beginner-friendly help pages. Another thing I forgot to mention when I wrote about MATLAB was: the more you read the help pages the more you see certain common, fundamental concepts repeated in multiple places. You will keep finding, say, x = 0:pi/100:2*pi; or plot(x,y,'-o','MarkerSize',10); on so many different, seemingly unrelated help pages. This is of a paramount importance for a beginner, not only does it help user memorize through repetition the recommended ways to write certain things, but even more importantly it develops a sense of familiarity with the language, which in turn creates an impression that it is actually possible to master the language, which in turn creates a desire to further explore the language. As of now, it’s everything opposite with Julia (for me). Because Julia Base docs explained it somewhere how you can/should initialize a range of x values so if you really want to learn go and find it. And before anyone asks: “Are you asking developers to repeat the complete beginner 's guide for each Base function’s help page?”, please just check any of the linked MATLAB help pages from @chadagreene’s post. As I stated and he quoted: docs are virtually nothing more than formally correct, least common denominator pieces of information standing in total isolation from the other pieces of information. For sure there is some middle ground between formally correct barren landscape they are now and daft regurgitation of basic concepts in each and every help page. MATALB help pages are basically a template how to do it. I understand this is an enormous amount of work so I do not think anyone has any right to ask the developers to actually do it.

5 Likes

I think the perception that you both have of the docs is mostly correct. There are some sections of the guide that are more humanly written, but in general it is a good manual for someone with a good background in computer sciences. After some experience in Julia I think there are many very good sections there, but that I understand now, not when I was starting with the language.

I think we as a community should have a more community-written manual. The official manual is constrained to be always exactly precise, concise in some sense. Maybe a wiki version would be nice. Newbies should be confortable to contribute to this manual, which is not the case for the official docs.

14 Likes

There is a secret that needs to be understood in order to write good software documentation: there isn’t one thing called documentation, there are four.

They are: tutorials, how-to guides, technical reference and explanation.

Lots of details in The Grand Unified Theory of Documentation

13 Likes

The documentation that you outline mixes (conflates) four distinct kinds of documentation (https://documentation.divio.com/). As does Matlab’s system. In many ways this is suboptimal. Perhaps here may Julia also lead the way as it does in language design. However, it needs to be recognized that this represents a major effort. Ever wonder what all those people at Mathworks actually do?

Looks my comment lost out to @jar1 who got it in first.

2 Likes

It’s interesting to note that MATLAB has been financially motivated to ensure their documentation is the most accessible for beginners among similar programming languages. MATLAB gets a significant portion of their income from university licenses, so they really must prioritize producing high-quality, effective documentation.

Here you see an indication of interest in MATLAB over time. You can really see summer break (the long dips), winter break (the second-longest dips) and even spring break (very short dip each year). It’s no wonder they have such high-quality, effective documentation.

6 Likes

If you think university students read the manual, you are definitely an idealist.

9 Likes

Not so long ago, someone requested help to translate to Julia all the examples of a statistics book, and as far as I remember, that was done in one week by the community.

I think we could develop quite quickly a lot of new documentation, but it has to be in a more relaxed environment, it can’t be by contributing to the Julia base (for instance, on base julia function doc comments).

6 Likes

As I said, I do not think anyone has any right to ask, let alone request, such effort from the developers who are writing the docs presumably in their own free time.

But I would argue though that the significant amount of writing the same developers generated answering endless basic questions on the discussion boards here and elsewhere could have been prevented if they invested 1/10 of that time expanding the docs they themselves wrote. Just my impression and fully in line with the examples you provided above.

4 Likes

You’re painting with a broad and inaccurate brush. There are tons of docstrings in Base Julia with an Examples section.

The sin documentation does in fact have a reference to sind in the “see also” section. Although unfortunately the hyperlink doesn’t work because there is a missing (@ref). Also, the reference to sind does appear to be somewhat new—it’s not in Julia version 1.6.

As I mentioned above, there are lots of docstrings in Base with examples. However, the examples have to be runnable using only Base (and standard library) Julia. There is no plotting in Base + StdLib Julia, hence there cannot be any examples of plotting in the Base docstrings. Furthermore, there are many different plotting packages. There is no canonical plotting package to be promulgated in base Julia docstrings.

It might be reasonable to have an example of broadcasting sin over a range in the (currently non-existent) Examples section of the sin docstring. But it’s a slippery slope. It sounds like you would be in favor of adding an example like this

julia> foo.(1:3)
3-element Vector{Int64}:
 2
 4
 6

to the docstring of every single function in Base that takes in a real number. That seems pretty excessive to me. As others have mentioned, I think you’re confusing reference documentation with tutorial documentation.

This is already well covered by stacktraces, though one can always quibble with formatting. It may sometimes take some patience to read stacktraces, but they contain a lot of useful information.

9 Likes

Perhaps one problem that we have is that the big blue “Documentation” button in the middle of the Julia language home page takes you straight to the Julia manual. So, there are probably a lot of new users who think they have to start by reading the manual, rather than by reading a tutorial. There should probably be an intermediate page that groups links to documentation into different groups based on documentation type, difficulty level, etc.

For example, here’s a screenshot of the old Python docs page, where you can see the Tutorial with the “start here” hint near the top:

And I guess they’ve changed things a bit, so now this is what you see if you click on the “Docs” menu item:

16 Likes

I think it would actually be worthwhile to have an official Julia Tutorial on the Julia Language website. In the meantime, I’ve opened the following issue:

https://github.com/JuliaLang/julia/issues/45135

13 Likes

You know what’s nice about documentation? It’s super easy to make pull requests! You don’t need to be a core developer for this! Or, if necessary, you can start an effort for an entirely separate Julia getting started tutorial-like website without anyones permission. It’s, of course, fine to just voice constructive critique but even better would be to address the actionable items yourself. :slight_smile:

(This would also scale much better since core developers are a rare species :grinning: )

7 Likes

The problem with asking new users to write documentation is that they don’t know the answers to their questions. Writing documentation is a job for experienced users.

13 Likes

As one of those people that spend a large amount of time answering beginner questions on both this forum and Slack, I assure you, I did not write the documentation. In a lot of cases, it’s even sufficient to just link the existing documentation to clarify what the original poster did not understand. I do agree that the sections & order things are explained in are… not good. Reworking that is a monumental task though and at least I don’t have enough time to spare to write a coherent new manual (as much as I’d like to) with technical documentation, a tutorial section per Stdlib and function reference sections.

I mean, that’s just not true. Yes, clicking the “edit on github” button is easy. That requires a github account though, which (from what I understand about the community) most non-student users don’t have. Setting that up takes time, when all they want to do is just use the darn thing. They didn’t sign up for improving docs, they want to get things done. Throwing “just fix it for us” at it sounds, at least to me, incredibly defensive & tone deaf. To add insult to injury, adjusting error messages can’t be done that way - you HAVE to dig around in internals to do that where you then come across incredibly undocumented and uncommented internals. If it’s that easy, why doesn’t everyone that answers questions on here do it?

Heck, even just “what should be documented” is a controversial topic and discussion about improving that largely seems to fall on deaf ears from core devs (or at least I’ve never seen a substantial commitment from anyone that’s deep in the weeds of julia internals to make that better). Worse, my personal experience has been that even the tiniest of (doc or QOL) changes takes MONTHS to merge.

I sometimes get the feeling/impression that if it’s not a sexy, high-profile, new feature (threading, BLAS, atomics, …) that a core developer already cares about (or even wrote and just merges themselves) and is 100% done, ready to merge, the person who opened the PR has to go around and nag/push for it in triage manually to get it done. (Aside: What even is discussed there nowadays? Last I participated, it was mostly about topics core devs were engaged in at that moment, not about reviewing the current state of issues, PRs & the repo in general (is that not the purpose of triage? Should something like that exist?). Follow ups to PRs that were not quite ready the last time triage looked at are not a thing, as far as I know.)

I can only imagine what a nightmare the review process would be even IF some kind soul puts in the work to rewrite docs. I can’t imagine it ever getting done without the vast majority (technical docs/references aside) being done ahead of time, outside of the setting of a PR, at which point from a purely economic standpoint it makes much more sense to publish that as a book instead.


I apologize if this sounds ranty, but I’m slowly getting frustrated with how our docs seem to stagnate and bitrot just because “ah just click that button and edit it”. I’ve started to click that button myself and open that PR, because suggesting it in this forum has (at least in my experience) never (or only extremely rarely) resulted in the person that asked to actually click the button and suggest an improvement.

28 Likes

There is a large range between “new users” and “core developers” though that I would consider to be experienced enough to write documentation.

Also, I wouldn’t agree with your statement entirely. If, as a new user, I just found a solution (say by checking multiple sources or even asking here on discourse or on slack) or crafted one on my own I could afterwards contribute this solution to the docs. However, I think the real issue here is that you would be largely distracted from what you wanted to do originally (and you already “wasted” lots of time on finding / crafting the solution in the first place) and you might not be willing to spend extra time anymore. (But, in some sense, the same applies to experienced / core devs to some extent.) Good documentation is a lot of work that needs to be done by someone, ideally a community.

5 Likes