A curiosity: with other languages, do you usually follow the docs to answer these kind of questions, or you search for them in google finding, with frequency, someone that asked a similar thing?
(I don’t know anything about Matlab docs, but for python I always go the google-way).
Yes, but I would not call it a problem “per se”, but more like a conclusion of the design of the language. The natural expressiveness of Julia multiple dispatch and type system allow getting into places that are hard, maybe impossible, to get on other languages.
@Akatz, not necessarily “frustration”, just a feeling of being lost way too often for my liking. As in, I’ll put Julia down and try something else that I’ll be able to figure out way quicker. Of the things you mentioned it is mostly the docs. Julia docs feel like I need to fully read and keep in mind the complete docs - for everything - before being able to form a working model in my head. It’s like each article holds only one piece of information devoid of context, examples, and application (I know that there are simple examples but stay with me here), and if you want to figure out those out the next piece has been explained in another article, then the next one, and so forth. Like, it’s too formal and dry as if it’s a legal explainer or academic paper, and not a help on how to use a tool. I do not have any issues with semantics or lack of dot chaining (if there is one), as that is something I need to learn and adapt to while learning a new language.
@Imiq, MATLAB does an excellent job in this regard, imho, they have a very, very practical approach regarding this. You can go to the MathWorks home page - not MATLAB help, but MathWorks home page - and type, say, “imread” in the search field, click on the first result and get the complete information, everything you need to complete your task. The page is formally correct, but not only formally correct, do you know what I mean? It’s not its main purpose to be academically formally correct utilizing the minimal language (albeit it is that too), the main purpose is to help you understand how to do your thing. Other languages arguably do not have it this nice, which is why I guess you asked the question - they do have a plethora of tutorials, discussion boards answers, etc. being more mature/popular languages than Julia. But that is the chicken and egg issue for Julia - in so many cases with other languages you do not even need to check the docs/web as I explained regarding my experience with python. Being far more intuitive (imho!) after reading the docs and far easier to pull something off in them simply makes me spend more time with them then with Julia. I imagine this makes more people use them, more people posting about them, and so on. So it’s not only about how old the language is, it’s also about how approachable it is. It all adds up and if it continues like this I do not see Julia ever be where python was at the identical age. It will just (“just”) remain a tool for a mathematician to solve a set of differential equations in 2.46 instead of 2.52 seconds and post the benchmark plot on Twitter.
Things where going well untill the end!
I think Julia achieved more than Python already for the age.
But it is not a python replacement for the people that is happy with python, it is a much more powerful tool, for who needs something that Python does not offer. And nothing to do with Twitter
Just one small example from a daily use: yesterday we realized that we needed to compute energies in a molecular simulation in a specific way. A C++ implementation of something similar, not the same, available in a very popular package, results to be 20x slower than a code we put up in one day in Julia. I have no idea why that C++ implementation is slow, and we didn’t care until we needed to compute something that is not exactly the same thing. Even the “naive” algorithm, which we wrote for testing, is fast enough to be used. And this is one code in which nothing special at all is done to improve performance.
That was not about competing with that other code for performance, we were happy with it, except that now it didn’t do what we wanted anymore.
Being able to write code for productive use that easily is what Julia is about. That changed completely the way I can write useful tools for my group and distribute them.
Where in the DiffEq docs does it read like this? The reason why we’ve focused so much more on the documentation than the help docstrings is precisely to have the interwoven information. For example, focusing mostly on the tutorials
https://diffeq.sciml.ai/stable/tutorials/ode_example/
and things like the common keyword arguments that cover all differential equation types:
https://diffeq.sciml.ai/stable/basics/common_solver_opts/
I’d be curious to have some specific points where this inter-module documentation does not come through well so we can improve it.
The average would be more like doing parameter optimization in 1 hour instead of 15 hours with MATLAB (with MEX C code). Without C code, it’s usually closer to >100x. If you’re going to say lower numbers, please cite and justify it.
I mean, Julia is that right now (edit: as Chris said, normally with bigger numbers), hahaha. But jokes aside, for what I see happening, it is growing really fast and for good.
One signal of that is that we are having this conversation, getting feedback, and listening to it with honesty, is the way to grow on what you didn’t know you lack.
Volker, Thanks for your post. I agree that Julia still has problems in many areas… I am using C/C++ most of the time, Python, Java, am with Julia since its 0.4 version. I’m very happy how better Julia is now comparing to what it used to be. I agree with you that references / documentation / tutorials could be much more convenient, but actually many packages has very good documentation. I’m OK with Julia’s debugging, maybe because I used to embedded systems 
I do not like several other things in Julia (like loading modules, precompilation, local variables etc etc). For all those years I did many attempts to get used to Plots but failed all the time.
Saying that, I’m trying to use Julia language when I have a chance. It’s much more convenient and faster then Python, when math is around.
BTW, does Julia really recompiles all the modules when we do ‘using’? If yes, then maybe somebody can point me what/where to read about the reasons of this behaviour?
Best regards
@Imiq, @ChrisRackauckas, @suavesito,
Oh my, perhaps I too should’ve posted a smiley at the end of that sentence! I understand why it might read very differently than how I intended. 
I hope there is no hard feelings.
And I guess that sentence leans on heavily on what I saw as the very essence of the original post. If I know how to do something that takes 15h in MATLAB, then it will be done in 15h. But if I cannot figure out how to do the same thing in Julia it doesn’t matter that it would take an hour - it will never be done. It just won’t. Again, saying this as a daft layman, take it as you will. If the problem is me I can absolutely assure you I accept it!
MK-1138, as a old Chemical Engineer I have much the same experience with Julia as you report.
But to be clear, I love Julia and I’m resisting any temptation to revert to another more mature (easier for non-computer scientists) language. My introduction to Julia was via JuMP and it was an amazing experience. The package functionality, stability, documentation and even the informal help provided by the community was 100% gold standard and all those involved should be very proud. Since then I have delved into Flux, http, smtpclient, sqlite and GLMakie and my learning curve for some of these has been very painful.
In the end I achieved most of what I wanted but at times the experience was just awful. Some of my issues related to persevering with VSCode, but I also had frustrations with documentation and obscure errors(from a chemical engineers perspective). Julia and it’s rich ecosystem of packages are clearly evolving fast on the back of a great language and the pain that comes with that fast growth is unavoidable without unlimited free development resources. I assume someone is guiding the ship with a gentle touch so not to kill the innovation so I’m optimistic we will see constant improvements to all these hurt points for years to come.
If it wasn’t for the patient and skilled people responding to my ignorant discord posts I would have given up a long time ago, so thanks.
Perhaps I’m not the natural target audience for Julia. That’s OK, but after programming for over 45 years I expected less pain, but I also didn’t expect to be having so much fun.
Thanks
Steve
I also find repl-driven debugging easier and many other people do as well. This illustrates the main issue with your article: It sounds like you assume everyone in the IT world have the same approach and style to programming, with the same needs, and therefore would find the article conclusions totally obvious and the critique spot on.
Having worked 40+ years in IT and used over 25 languages, Julia is my absolute favorite. People I highly admire love Rust. We do different things, approach programming with different mind sets, and have different needs. I prefer functional paradigm, find multiple dispatch amazing. don’t find OO a useful paradigm, I love dynamic, repl driven coding, and find Julia tooling great. I find the official Julia documentation superb and well written. Like in many other languages, open source package doco varies greatly by author. For me Julia meets the Goldilocks test.
If I were to critique a language I don’t like, I would focus more on explaining why it’s underlying paradigm isn’t useful for me, given my programming approach and needs. I would also stress the things I found interesting and useful that are missing in a language I prefer.
How do you edit structs in this workflow?
I think that’s the simplest way : Search and replace MyStruct → MyStructv2
What’s a specific issue you had with the DiffEq documentation? Can you point one out? I’m trying to find out what can be actionable here. Please make this more specific.
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.
Mostly Docs.
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.
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.
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.
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.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]).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:
Error on Line 5 in rationalize():...)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.
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.
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.
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