# Blog post about my experiences with Julia

**URL:** <https://discourse.julialang.org/t/blog-post-about-my-experiences-with-julia/79976>\
**Category:** Community\
**Created:** [April 25, 2022, 8:19am UTC](https://discourse.julialang.org/t/blog-post-about-my-experiences-with-julia/79976 "2022-04-25T08:19:00Z")\
**Posts on this page:** 20\
**Page:** 10

<div class="post-metadata">

**Author:** ![johnmyleswhite](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/johnmyleswhite/32/31_2.png) [@johnmyleswhite](https://discourse.julialang.org/u/johnmyleswhite)\
**Post date:** [May 1, 2022, 12:35pm UTC](https://discourse.julialang.org/t/blog-post-about-my-experiences-with-julia/79976/183 "2022-05-01T12:35:30Z")

</div>

> 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.

---

<div class="post-metadata">

**Author:** ![johnmyleswhite](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/johnmyleswhite/32/31_2.png) [@johnmyleswhite](https://discourse.julialang.org/u/johnmyleswhite)\
**Post date:** [May 1, 2022, 12:38pm UTC](https://discourse.julialang.org/t/blog-post-about-my-experiences-with-julia/79976/184 "2022-05-01T12:38:28Z")

</div>

[![](https://global.discourse-cdn.com/julialang/original/3X/9/2/92bd12cf760634bb86270811081eb1a9dfb3aa1b.jpeg "How to edit the Julia docs on GitHub") ](https://www.youtube.com/watch?v=0gshzIYqkcY)

---

<div class="post-metadata">

**Author:** ![MK-1138](https://avatars.discourse-cdn.com/v4/letter/m/22d042/32.png) [@MK-1138](https://discourse.julialang.org/u/MK-1138)\
**Post date:** [May 1, 2022, 12:45pm UTC](https://discourse.julialang.org/t/blog-post-about-my-experiences-with-julia/79976/185 "2022-05-01T12:45:56Z")

</div>

> [@CameronBieganek](#):
>
> It sounds like you would be in favor of adding an example like this
> 
> (…)
> 
> to the docstring of _every single function_ in Base that takes in a real number. That seems pretty excessive to me.

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.

---

<div class="post-metadata">

**Author:** ![johnmyleswhite](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/johnmyleswhite/32/31_2.png) [@johnmyleswhite](https://discourse.julialang.org/u/johnmyleswhite)\
**Post date:** [May 1, 2022, 12:55pm UTC](https://discourse.julialang.org/t/blog-post-about-my-experiences-with-julia/79976/186 "2022-05-01T12:55:54Z")

</div>

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:

1. Focus on documenting functions first. Forget the rest of the language for a bit – just figure out how to get the documentation of functions to a place that all parties here agree is good enough and meets the bar you feel other languages have set.
2. Rank order the functions in Base by the importance of documenting them.
3. Set up a partnership model in which an expert who can explain what the function does and a non-expert who wants the documentation to be better co-own the writing process and work together.
4. Set up a delivery cadence – say one function per week per pair. I for example am happy to partner as an “expert” with someone like @chadagreene or @MK-1138 to start on the documentation for sin.
5. Keep going down the rank order list function-by-function until things have gotten better.

---

<div class="post-metadata">

**Author:** ![lmiq](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/lmiq/32/18314_2.png) [@lmiq](https://discourse.julialang.org/u/lmiq)\
**Post date:** [May 1, 2022, 1:04pm UTC](https://discourse.julialang.org/t/blog-post-about-my-experiences-with-julia/79976/187 "2022-05-01T13:04:08Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![mcabbott](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mcabbott/32/6603_2.png) [@mcabbott](https://discourse.julialang.org/u/mcabbott)\
**Post date:** [May 1, 2022, 1:13pm UTC](https://discourse.julialang.org/t/blog-post-about-my-experiences-with-julia/79976/188 "2022-05-01T13:13:41Z")

</div>

The lack of a hyperlink from `sin` to `sind` is a mistake in [this PR](https://github.com/JuliaLang/julia/pull/38606/files#diff-faa5f0835bd28c4a33e6603e208a9236034568a4abc7adec4995afb64550d0bdR420-R424). 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.

> [@](#):
>
> Where’s an example that _shows_ how to calculate and plot a sine wave?

For an example of this, NNlib has uses [UnicodePlots in docstrings](https://github.com/FluxML/NNlib.jl/blob/master/src/activations.jl#L27-L41). 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?

---

<div class="post-metadata">

**Author:** ![ericphanson](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/ericphanson/32/215186_2.png) [@ericphanson](https://discourse.julialang.org/u/ericphanson)\
**Post date:** [May 1, 2022, 1:15pm UTC](https://discourse.julialang.org/t/blog-post-about-my-experiences-with-julia/79976/189 "2022-05-01T13:15:44Z")

</div>

By the way, Tim Holy made a similar video awhile back:

[![](https://global.discourse-cdn.com/julialang/original/3X/7/8/78788c381cf1489a79ed388897b5896efbae46b4.jpeg "Making Julia documentation better") ](https://www.youtube.com/watch?v=ZpH1ry8qqfw)

---

<div class="post-metadata">

**Author:** ![lmiq](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/lmiq/32/18314_2.png) [@lmiq](https://discourse.julialang.org/u/lmiq)\
**Post date:** [May 1, 2022, 1:16pm UTC](https://discourse.julialang.org/t/blog-post-about-my-experiences-with-julia/79976/190 "2022-05-01T13:16:24Z")

</div>

> [@mcabbott](#):
>
> should it be taken for granted that readers know what `sin` looks like?

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.

---

<div class="post-metadata">

**Author:** ![johnmyleswhite](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/johnmyleswhite/32/31_2.png) [@johnmyleswhite](https://discourse.julialang.org/u/johnmyleswhite)\
**Post date:** [May 1, 2022, 1:16pm UTC](https://discourse.julialang.org/t/blog-post-about-my-experiences-with-julia/79976/191 "2022-05-01T13:16:26Z")

</div>

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:

```julia
  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.

---

<div class="post-metadata">

**Author:** ![lmiq](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/lmiq/32/18314_2.png) [@lmiq](https://discourse.julialang.org/u/lmiq)\
**Post date:** [May 1, 2022, 1:17pm UTC](https://discourse.julialang.org/t/blog-post-about-my-experiences-with-julia/79976/192 "2022-05-01T13:17:29Z")

</div>

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.)

---

<div class="post-metadata">

**Author:** ![johnmyleswhite](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/johnmyleswhite/32/31_2.png) [@johnmyleswhite](https://discourse.julialang.org/u/johnmyleswhite)\
**Post date:** [May 1, 2022, 1:24pm UTC](https://discourse.julialang.org/t/blog-post-about-my-experiences-with-julia/79976/193 "2022-05-01T13:24:13Z")

</div>

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](https://www.rdocumentation.org/packages/stats/versions/3.6.2/topics/lm)

---

<div class="post-metadata">

**Author:** ![Volker\_Weissmann](https://avatars.discourse-cdn.com/v4/letter/v/c2a13f/32.png) [@Volker\_Weissmann](https://discourse.julialang.org/u/Volker_Weissmann)\
**Post date:** [May 1, 2022, 1:57pm UTC](https://discourse.julialang.org/t/blog-post-about-my-experiences-with-julia/79976/194 "2022-05-01T13:57:37Z")

</div>

> [@MK-1138](#):
>
> 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 like these kind of docs, but I don’t think Julia’s docs are like that.

---

<div class="post-metadata">

**Author:** ![Volker\_Weissmann](https://avatars.discourse-cdn.com/v4/letter/v/c2a13f/32.png) [@Volker\_Weissmann](https://discourse.julialang.org/u/Volker_Weissmann)\
**Post date:** [May 1, 2022, 2:45pm UTC](https://discourse.julialang.org/t/blog-post-about-my-experiences-with-julia/79976/195 "2022-05-01T14:45:59Z")

</div>

I like Julia’s `sin` documentation.

> [@"chadagreene](#):
>
> As one example, take a look at the docs for the [`sin`](https://docs.julialang.org/en/v1/base/math/#Base.sin-Tuple%7BNumber%7D) 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.
> 
> - What should a user do if their `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` .

PR to change “[sind]” to a hyperlink to “[sind]” is under way…  
Also, searching for radian or degree yields [Mathematics · The Julia Language](https://docs.julialang.org/en/v1/base/math/#Base.Math.deg2rad) and [Mathematics · The Julia Language](https://docs.julialang.org/en/v1/base/math/#Base.Math.rad2deg)

> [@"chadagreene](#):
>
> - What if `x` is complex?

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](https://en.wikipedia.org/wiki/Sine_and_cosine#Complex_arguments).

> [@"chadagreene](#):
>
> - Most importantly: Where’s an example that _shows_ how to calculate and plot a sine wave?

This example belongs in the documentationn of Plots.jl not in the documentation of Base.math.

> [@"chadagreene](#):
>
> expected to know how to define a range of `x` values, expected to know to include a `.` in the `sin` call to calculate the sine over multiple values,

If you do not know how to do that, you should read the manual, starting from [Getting Started · The Julia Language](https://docs.julialang.org/en/v1/manual/getting-started/)

> [@"chadagreene](#):
>
> 1. Identify the location of the problem. (e.g., `Error on Line 5 in rationalize():...` )

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.

> [@"chadagreene](#):
>
> Actionable item: Write all error messages as _complete sentences_ following this formula, in this order:
> 
> 1. Describe the technical cause of the problem (in human language).

For more experienced people, human language is longer and less precise than “formal language”.

> [@"chadagreene](#):
>
> 1. Conclude with some gentle advice for what can be done about the problem.

This is not an easy task. The compiler does not always know how the problem can/should be solved.

---

<div class="post-metadata">

**Author:** ![CameronBieganek](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/cameronbieganek/32/6915_2.png) [@CameronBieganek](https://discourse.julialang.org/u/CameronBieganek)\
**Post date:** [May 1, 2022, 3:22pm UTC](https://discourse.julialang.org/t/blog-post-about-my-experiences-with-julia/79976/196 "2022-05-01T15:22:05Z")

</div>

> [@MK-1138](#):
>
> It’s either one extreme or the other, no middle ground between them.

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:

> <https://github.com/JuliaLang/julia/pull/45137>
>
> Some "see also" links from #38606 were missing \`(@ref)\` and thus not really link…s. 
> 
> Also adds a few more such links, and adds examples for \`sin\` and a few other functions.

> [@MK-1138](#):
>
> formally correct nuclei of utterly isolated information that the docs are at the moment

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.

---

<div class="post-metadata">

**Author:** ![PetrKryslUCSD](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/petrkryslucsd/32/215825_2.png) [@PetrKryslUCSD](https://discourse.julialang.org/u/PetrKryslUCSD)\
**Post date:** [May 1, 2022, 3:26pm UTC](https://discourse.julialang.org/t/blog-post-about-my-experiences-with-julia/79976/197 "2022-05-01T15:26:40Z")

</div>

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, …

---

<div class="post-metadata">

**Author:** ![dmolina](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/dmolina/32/5246_2.png) [@dmolina](https://discourse.julialang.org/u/dmolina)\
**Post date:** [May 1, 2022, 3:40pm UTC](https://discourse.julialang.org/t/blog-post-about-my-experiences-with-julia/79976/198 "2022-05-01T15:40:13Z")

</div>

I completely agree. The documentation reference should not be seen as the only documentation by new users.

---

<div class="post-metadata">

**Author:** ![chadagreene](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/chadagreene/32/34924_2.png) [@chadagreene](https://discourse.julialang.org/u/chadagreene)\
**Post date:** [May 1, 2022, 3:44pm UTC](https://discourse.julialang.org/t/blog-post-about-my-experiences-with-julia/79976/199 "2022-05-01T15:44:40Z")

</div>

> [@CameronBieganek](#):
>
> 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.

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.

---

<div class="post-metadata">

**Author:** ![CameronBieganek](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/cameronbieganek/32/6915_2.png) [@CameronBieganek](https://discourse.julialang.org/u/CameronBieganek)\
**Post date:** [May 1, 2022, 4:08pm UTC](https://discourse.julialang.org/t/blog-post-about-my-experiences-with-julia/79976/200 "2022-05-01T16:08:41Z")

</div>

> [@chadagreene](#):
>
> Is this a technical problem that can never be overcome, or is it purely an imaginary limitation?

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?

---

<div class="post-metadata">

**Author:** ![chadagreene](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/chadagreene/32/34924_2.png) [@chadagreene](https://discourse.julialang.org/u/chadagreene)\
**Post date:** [May 1, 2022, 4:25pm UTC](https://discourse.julialang.org/t/blog-post-about-my-experiences-with-julia/79976/201 "2022-05-01T16:25:24Z")

</div>

> [@PetrKryslUCSD](#):
>
> 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.

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.

> [@PetrKryslUCSD](#):
>
> 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.

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](https://documentation.divio.com/). 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](http://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](https://youtu.be/t4vKPhjcMZg) 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.

---

<div class="post-metadata">

**Author:** ![jules](https://avatars.discourse-cdn.com/v4/letter/j/41988e/32.png) [@jules](https://discourse.julialang.org/u/jules)\
**Post date:** [May 1, 2022, 4:27pm UTC](https://discourse.julialang.org/t/blog-post-about-my-experiences-with-julia/79976/202 "2022-05-01T16:27:02Z")

</div>

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.

[Previous page](https://discourse.julialang.org/t/blog-post-about-my-experiences-with-julia/79976.md?page=9)

[Next page](https://discourse.julialang.org/t/blog-post-about-my-experiences-with-julia/79976.md?page=11)