My experience with learning Julia and various great packages for its ecosystem make me aware that documentation is in this case much more important than in the case of languages like C, C++, Python, Fortran (you can add more to these list). First of all, many of these languages are settled and handbook written 20 years ago still can be pretty good. Second, if languages like C++ have release as C++ 20, there previous version are often maintained for long time and reliable. These same can be said about they ecosystem.
Julia and its ecosystem on the other hand changed in innumerable many ways from 2012 (even from 2018). Changed names of built-in functions (
quit was replaced by
exit), rearranged standard libraries, changed conventions of naming functions (once upon time we had
int(x) function), very important changes in internals workings and performance (like issue 50% performance regression in map! form Julia 1.2 to 1.4), etc., etc. In the packages ecosystem breaking changes are even more common, since when I last check very few of packages that I use reached version 1.0 (in May this year even DataFrames.jl didn’t have 1.0 release).
From these reasons teaching materials age very fast and when you study them you may need to check many additional materials (luxuriant imagination in guessing new names of functions is also useful). To this point I find three reliable, (mostly) up to date sources for understanding Julia and Julia’s ecosystem.
- Reading source code.
- Posting your problem on Julia Discourse.
- Reading official documentation.
Unfortunately, changes in Julia world are so fast and big that even official documentation for packages can be outdated or buggy in many points. There are many reasons for that. Unnoticed change in Julia internals (50% performance regression in map! form Julia 1.2 to 1.4), simple bug in examples of code, etc.
Once than more I tried to correct some of that problems and in that way I discovered that both GitHub and chatroom are often suboptimal. When I try to post some problems to chatroom as Gitter they are mostly lost in a wall of text. Opening issue on GitHub seems to me inconvenient, since talking about documentation can open quite long discusion, about how to make it better, more approachable, what about personal preference, etc. My personal feeling is that such discussion should be avoided on GitHub and numbers of issues keep to minimum.
In current state various documentation related discussion are mostly in “First steps” or “Usage” category. I wonder if separate “Documentation” category can help use better organize work on it? I think that can bring more order to current discusion, but I can be wrong. So I want to hear your opinions.