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.
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.
If you think university students read the manual, you are definitely an idealist.
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).
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.
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.
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:
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:
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. 
(This would also scale much better since core developers are a rare species 
)
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.
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.
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.
Actually there is
https://en.m.wikibooks.org/wiki/Introducing_Julia
It’s a great ressource. It helped me understand many things that were not clear for me from the official docs.
Now I’m out already. I might want to contribute, but have no idea how to do a pull request.
I offered to help with the Haskell documentation, but was advised to do a pull request. So, that went nowhere.
That sounds like a job for a scripting language - Python, or Ruby or PowerShell perhaps - where your use case and the advantages of Julia are not necessarily a good match.
I had a go at Rust.
I liked the compiler at lot. Even the infamous borrow checker didn’t faze me. I am invincible!
Then I read a blog post about addressing the borrow checker AND optimising the code, So, I am starting to wonder if my assessment was slightly premature.
That’s nice. There could be a place to create function help entries like the ones Matlab has. As mentioned, it is not evident that the official docs could have plot examples for every function, and repeat patterns at exhaustion.
The problem with contributing to the official docs are many. Because they are official, they cannot contain stuff outside base. Contributions have to be perfect: adhere to style, no typos, etc. The contribution to function help entries is even more complicated because they mess up with the code itself. I don’t think that the “pull request” system is the problem, the problem is that it cannot be a relaxed contribution, there is too much responsibility in pull requests to base. And as such, they require careful revision and naturally a slow process.
I wonder if MATLAB’s docs being structured as one function per page helps provide a place for more extensive docs. Documenter docs are usually done as a long list of related functions per page.
Interestingly, although there is no plotting in Python stdlibs or in Numpy, nevertheless the Numpy docs for numpy.sin are much like the Matlab doc and include a plotting example with matplotlib:
Well, for my part I did try - twice - to show basic human consideration towards the developers and state that no one is entitled to their free time. I’d appreciate it if the same courtesy would be extended to me. While I’m not a programmer, I do provide a fair share of pro-bono work in my industry, and try to participate in as many charitable events as my time/finances permit.
Not to mention what others already pointed out, imagine how it would it look if someone like me actually wrote the examples for what I just had to ask about myself, and the developer was kind enough to answer - how is this more efficient for anyone involved? How many of those pull request changes do you realistically think would be incorporated? How many revisions or the touch ups from the approver would it take?
@Sukera, just to clarify - I did receive, quite often actually, answers from the developers of a particular package. I felt grateful and even humbled but it also got me thinking if this was the best use of their time? The docs exist, so how come they are answering these fairly basic questions here on the boards? How many people will ask this or a similar question, where is the threshold where it’s more efficient to put this into the docs and preempt the queries? I guess they are glad to see people using their packages and showing interest so they are kind enough to answer but sooner or later the life will take over and they’ll stop answering. Then what? Perhaps people like you will take over but here you describe submission issues you had.
