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.
The counter to this aphorism is that experienced users are the most likely to be blinded to what’s not obvious to someone who knows less than them. There’s no outsourcing model that works here – it’s a partnership or nothing ever gets done.
Aaaand here it is. It’s either one extreme or the other, no middle ground between them. If someone notes that formally correct nuclei of utterly isolated information that the docs are at the moment would be more useful to the beginners if they are put in some sort of context, well that automatically means they are asking for the same example to be added to the docs for eVeRy SiNgLe FuNcTiOn. I do not understand where these notions are coming from, and more so in the same thread where it was already explicitly clarified that’s not being asked.
I think this thread is rapidly spiraling into non-actionability that will lead to resentment without much insight and definitely without specific improvements.
I suggest the following:
I suggest a slightly different approach: create a fork into an “unofficial” version, and give everyone interested editing power. Start experimenting about the kind of content, release docs often, and let this create a source of ideas for the official docs that are much slower to change, and subject to contrains of different sort.
Why: let us suppose that I create a new section on the manual to contain an entry like the sin one of numpy/Matlab.
Then I do the same for a handful of functions. That won’t be merged into the main docs, because it will be very uncomplete. There tenths of other functions that should be documented similarly before the merging makes sense.
Thus, these suggestions will never be merged, and that will be frustrating. We need a model that is more dynamical and stimulating.
The lack of a hyperlink from sin to sind is a mistake in this PR. From the response to that, I believe that adding more & better examples is usually welcomed, and doesn’t have to get stuck in review hell.
I don’t know whether everyone wants them as long as the Matlab (or Mathematica) per-function docs; keeping that much text up to date might become a burden. (And might require some more complicated mechanism to store and display the text than help?> sin.) But there’s a lot of room for incremental improvement first.
For an example of this, NNlib has uses UnicodePlots in docstrings. It wouldn’t be crazy to show the shape of the functions in Base, although I’m not sure which ones — should it be taken for granted that readers know what sin looks like?
By the way, Tim Holy made a similar video awhile back:
It is not about that. In that sense the help entries for common mathematical functions is useless. The point is to expose the user to minimally set of operations that make sense in the language.
But that is not the place for the function doc comment entries.
Having a separate repo doesn’t seem like a bad idea to me, but I think you’re assuming the best approach is quite different from what I’d advocate for. Let’s take sin as an example:
sin(x)
Compute sine of x, where x is in radians.
────────────────────────────────────────────────────────────────────────────
sin(A::AbstractMatrix)
Compute the matrix sine of a square matrix A.
If A is symmetric or Hermitian, its eigendecomposition (eigen) is used to
compute the sine. Otherwise, the sine is determined by calling exp.
Examples
≡≡≡≡≡≡≡≡≡≡
julia> sin(fill(1.0, (2,2)))
2×2 Matrix{Float64}:
0.454649 0.454649
0.454649 0.454649
I’d argue the simplest first step is to get other argument types for sin to have as much depth (or more) as the AbstractMatrix type has. You can make these pull requests hyper-local – doing a good job for a single function is per se valuable and doesn’t need to block on something broader.
Exactly, I’m not talking about these doc entries mostly. Those are much more constrained.
(Ps. If nothing comes out of this, I will start the project In a month or so, and I’ll be back with a more specific idea.)
I’m pushing back on the idea that having them be constrained is good. One of the things I find disappointing in Julia’s documentation is that there’s been too little depth put into the in-REPL documentation, which is almost the only thing I ever use.
I totally support creating other separate kinds of documentation as well, but I think it’s extremely reasonable to expect that most functions in Julia should have documentation at the bar of base R: lm function - RDocumentation
I like these kind of docs, but I don’t think Julia’s docs are like that.
I like Julia’s sin documentation.
PR to change “[sind]” to a hyperlink to “[sind]” is under way…
Also, searching for radian or degree yields Mathematics · The Julia Language and Mathematics · The Julia Language
Then I expect sin to return the sin of x. The definition of the sine of a complex number can be found on e.g wikipedia.
This example belongs in the documentationn of Plots.jl not in the documentation of Base.math.
If you do not know how to do that, you should read the manual, starting from Getting Started · The Julia Language
This is not an easy task. The compiler only knows that one of the calls in the stacktrace is the location of the problem, but it does not know which call is the problem.
For more experienced people, human language is longer and less precise than “formal language”.
This is not an easy task. The compiler does not always know how the problem can/should be solved.
You’re right, there is a middle ground. We don’t need a broadcasting example for every single function in Base, but it is reasonable to have broadcasting examples for the math functions like sin, cos, and tan. @mcabbott has started the process of adding those examples in a new PR:
I think you’re exaggerating a little. There are some docstrings, like the docstring for sin, which are rather light on information, but there are lots of functions in Base that are well documented, with useful explanation, examples, and references to other functions.
I am sorry if repeating myself will grate: the structure of the Julia documentation is not right.
There should be a clear separation between REFERENCE (used when working, theoretical knowledge), EXPLANATION (theoretical, used when studying), TUTORIALS (practical, for studying), and HOW-TO (practical, used when working).
If the structure was right, it would be easier for people to contribute. Because right now there are always questions: should this be put here? Where is the right place for it? And, invariably long discussions, no action, ensue.
It would be good (as @CameronBieganek pointed out above) if the blue documentation button were to lead to a IF-ELSE page: do you want to see reference, tutorials, …
I completely agree. The documentation reference should not be seen as the only documentation by new users.
Is this a technical problem that can never be overcome, or is it purely an imaginary limitation?
Perhaps it’s not how the founding devs envisioned the documentation, but we must step back and acknowledge the value of an example that produces a simple plot. An MWE gives users everything they need to use a function, understand how it works, and make the abstract inner-workings of the function come to life. I don’t understand the case against this, other than that it’s not how it’s been done so far.
Most, if not all, of the examples use the jldoctest flag, which tells Documenter.jl to actually run the code and check that the output matches the output shown in the example. So an example that includes a call to plot will fail the doctest because the plot function won’t be found.
Of course there’s no fundamental technological limitation. It could be done if it was decided that it should be done. But there’s still the question of which plotting package to use in examples. Any usage of a plotting package in the Base docs amounts to an implicit endorsement of a third-party package as the “blessed” package for plots. Which plotting package should be endorsed? Plots.jl, Makie.jl, Gnuplot.jl, Gadfly.jl, Gaston.jl?
Indeed, the structure is not right. The docs currently don’t go beyond the REFERENCE section. Several posts in this thread point to explanations, tutorials, and how-tos as proof that other parts of documentation can be found out there on the internet somewhere, if you look in the right place, but this scattered nature of the documentation is a major source of confusion for me as a beginner. Having one common, reliable place to look for documentation would be tremendously valuable, instead of having to be filled with this constant anxiety that I’m missing something.
Totally. It would be easier for users to find the information and easier for developers to write the documentation if the structure were more clear, as pointed above. However, that’s not to say the different parts of the documentation should be pulled apart and stored in separate places around the internet.
Also, the ideas in the documentation.divio.com site are definitely insightful to consider, but note that it’s just someone’s opinion, and is not supported by any scientific evidence on the site or in Procida’s lecture. His main thesis seems to be that because learning and understanding are separate things, they must be separated in the teaching process. In the lecture, he gives the example of teaching a child to cook, saying that there should be absolutely no explaining during such a tutorial. I don’t know about you, but to learn how to cook, I really needed my mother to explain why we peel the carrots or preheat the oven.
In the case of Julia documentation, I definitely agree that a Reference section should be clearly distinguished from the tutorials/explanations/how-tos, but note that the lines between “used when studying” and “used when working” are never clear in real life. We learn when we try to accomplish tasks, so whether it’s an academic exercise to analyze some data, or a learning experience that occurs while analyzing data at work, the lines are always blurred in real life. Accordingly, blending concepts with technical know-how is essential for developing independence, whether in code documentation or a cooking tutorial.
I think putting a plot for sin into the base documentation of Julia is overkill. The maintenance burden of the docs would be much higher if plotting was included, and that would effectively exclude other plotting packages than whichever one would be chosen. I can see that in Python matplotlib is kind of the canonical plotting solution, but I don’t think we have that. Plots is only an interface for other libraries, and Makie (just because I can speak to that) doesn’t want to be the “only” plotting package either.
Matlab also has its own canonical plotting engine, so they have it easy in terms of whether to include plots or not, it can be done without additional maintenance burden (apart from short plotting code).
I’d rather see efforts to write good introductory content for Julia’s plotting and data analysis packages, and try and link these better amongst each other. So it should be easy to find tutorials showing plotting packages etc from the main Julia page, recognizing that that’s something a lot of people want to find out about. But it should not really be in the main Julia docs, because centralization like that doesn’t really reflect the diverse ecosystem we have.