Can adding "Documentation" category to Julia Discourse be a good idea?

Meta Discussion
#1

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.

  1. Reading source code.
  2. Posting your problem on Julia Discourse.
  3. 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.

1 Like
#2

Here’s my take on this:
I will split this into two topics: versioning and discoverability.

I remember when me and some colleagues set about learning Python and machine learning and encountered the same problem, but much more severe: tons and tons of blogposts and tutorials which we never got working because they haven’t even documented if they used Python 2 or 3 (we were absolute beginners and had no idea about the differences). This is the perfect example of more “documentation” means “no documentation”.
Actually I got so frustrated with the Python situation that I convinced all of them to switch to Julia:)).
And yes, there was way less documentation, but what we found was good and got us going very fast.

This experience taught me that “google it” is not always the best approach and most beginners use this method for getting something going fast. I learned to rely more and more on the official github documentation (something I never imagined existed, being primarily a Matlab user), so here I agree with your three main sources of information. Of course some of the github documentation might be outdated, but there is not much to do about it other than submit and issue or PR. I’m always very grateful when I see even minimal documentation on github packages, given the amount of work invested there.

The takeaway for versioning: this problem is not Julia specific and simply educating the blogpost authors to post their package versions used (or better, provide a github link with the project and Manifest.toml) would be very helpful. (this could apply also for youtube tutorials)

Regarding discoverability, I really like https://julialang.org/learning/ and https://juliahub.com/. Pinning these would do no harm. Otherwise newcomers will search blindly on google and probably find an outdated tutorial or package.

I don’t think it’s possible to have a Documentation category containing hundreds of links to documentation (it would be very hard to maintain as well, and we have juliahub which is awesome).
But I agree that a Documentation category containing some links like the two above would be useful(or maybe pin a post with such relevant links in First Steps?).
I wonder if there are any statistics on how many people visited the julialang learning page vs. how many visited discourse.

1 Like
#3

I think @KZiemian is proposing a new category to support people interested in updating and improving the documentation, to organize discussions about it (rather than to collect links).

1 Like
#4

I think that PRs/issues are much better for this.