# Non-friendly documentation

**URL:** <https://discourse.julialang.org/t/non-friendly-documentation/38109>\
**Category:** New to Julia\
**Tags:** question, documentation\
**Created:** [April 23, 2020, 9:24pm UTC](https://discourse.julialang.org/t/non-friendly-documentation/38109 "2020-04-23T21:24:33Z")\
**Posts on this page:** 20\
**Page:** 6

<div class="post-metadata">

**Author:** ![c42f](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/c42f/32/52842_2.png) [@c42f](https://discourse.julialang.org/u/c42f)\
**Post date:** [April 30, 2020, 9:11pm UTC](https://discourse.julialang.org/t/non-friendly-documentation/38109/103 "2020-04-30T21:11:34Z")

</div>

> [@blackeneth](#):
>
> God help you if you see a ? b : c and try to search for “[?](https://docs.julialang.org/en/v1/manual/control-flow/#man-conditional-evaluation-1)”!

I’ve made it so that searching for either `?` or `?:` in REPL help mode will tell you about it: [Help mode documentation for ternary operator by c42f · Pull Request #35637 · JuliaLang/julia · GitHub](https://github.com/JuliaLang/julia/pull/35637) 🙂

---

<div class="post-metadata">

**Author:** ![c42f](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/c42f/32/52842_2.png) [@c42f](https://discourse.julialang.org/u/c42f)\
**Post date:** [April 30, 2020, 10:01pm UTC](https://discourse.julialang.org/t/non-friendly-documentation/38109/104 "2020-04-30T22:01:14Z")

</div>

> [@purplishrock](#):
>
> i will make another attempt at figuring out PRs again. I’m just pretty sure that the people who know and understand the package/PR environment don’t realize that it’s really not very easy, and figuring it out so that you can submit a 10 line example is a bit daunting.

For what it’s worth, I vividly remember the fish-out-of-water feeling which came with learning `git`. And this was after already knowing and using another version control system fairly extensively.

`git`’s command line interface is like a power tool with a hidden safety button. Or rather, more like a power tool with ten cryptically labeled safety buttons of different colors, three of those hidden inside the machine behind a little door which says “Beware of the Leopard”, nestled next to a knob which will chop your arm off.

Don’t worry though, restoring your missing limbs is easily done using time travel - just open the door and press the button labelled `reflog`. And if that’s not enough, the `cat-file` button can bring them back from a parallel universe if you recite their One True Name.

---

<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:** [April 30, 2020, 10:02pm UTC](https://discourse.julialang.org/t/non-friendly-documentation/38109/105 "2020-04-30T22:02:33Z")

</div>

Come on, it’s not that bad. As far as I know, git’s actions are always undoable.

---

<div class="post-metadata">

**Author:** ![Zach\_Christensen](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/zach_christensen/32/7220_2.png) [@Zach\_Christensen](https://discourse.julialang.org/u/Zach_Christensen)\
**Post date:** [April 30, 2020, 10:12pm UTC](https://discourse.julialang.org/t/non-friendly-documentation/38109/106 "2020-04-30T22:12:06Z")

</div>

Yeah but it’s not always easy to undo them.

---

<div class="post-metadata">

**Author:** ![c42f](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/c42f/32/52842_2.png) [@c42f](https://discourse.julialang.org/u/c42f)\
**Post date:** [April 30, 2020, 10:15pm UTC](https://discourse.julialang.org/t/non-friendly-documentation/38109/107 "2020-04-30T22:15:10Z")

</div>

> [@PetrKryslUCSD](#):
>
> far as I know, git’s actions are always undoable

Yes of course, that’s what `git reflog` is for! (Or is it `git rebase --abort` or maybe `git cherry-pick --abort` or `git reset --soft HEAD^`, or `git cat-file blob e4612fec296d590f4e226d4ce56a4fcff1c674f1 > restored`)

By the way, I love git and I hope it’s clear my post was meant to be a joke (edited slightly to make this clearer)! But it’s also not entirely wrong 🙂

---

<div class="post-metadata">

**Author:** ![DNF](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/dnf/32/10191_2.png) [@DNF](https://discourse.julialang.org/u/DNF)\
**Post date:** [April 30, 2020, 10:18pm UTC](https://discourse.julialang.org/t/non-friendly-documentation/38109/108 "2020-04-30T22:18:14Z")

</div>

> [@PetrKryslUCSD](#):
>
> Come on, it’s not that bad. As far as I know, git’s actions are always undoable.

I’ve been using git daily at work for the past five+ years, and I have _no_ idea how it works. I certainly wouldn’t know how to create a PR, and _definitely_ not how to _undo_ something.

This xkcd strip is probably supposed to be a bit tongue in cheek: [xkcd: Git](https://xkcd.com/1597/) but to me it is the plain and un-hyperbolic truth.

In all the countless number of hours I’ve spent working with git, reading documentation, tutorials, stack overflow posts, etc. I’ve learned basically _nothing_.

---

<div class="post-metadata">

**Author:** ![purplishrock](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/purplishrock/32/13451_2.png) [@purplishrock](https://discourse.julialang.org/u/purplishrock)\
**Post date:** [April 30, 2020, 11:58pm UTC](https://discourse.julialang.org/t/non-friendly-documentation/38109/109 "2020-04-30T23:58:48Z")

</div>

yes. it is that bad.  
it’s very very cryptic  
i find it hard to do simple things.  
i am ALWAYS reading documentation to find out how to do absolutely anything. nothing about it is intuitive in the least.

the last time i remember trying to find a diff it involved having to look up a 32-character commit code of some sort, like this one,

e4612fec296d590f4e226d4ce56a4fcff1c674f1`

and finding that 32-character code was something i had to go lookup.

the documentation is terrible because it’s too busy explaining all the tricky stuff instead of explaining why

git diff filename

doesn’t actually work. which is still utterly unbelievable to me.

it’s ridiculous.

p.s. ok. i’ll stop. i’m going to spend my time looking at the very useful links people have provided which makes it easy to make small changes to docs using github. that would be much better than my useless ranting.

---

<div class="post-metadata">

**Author:** ![c42f](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/c42f/32/52842_2.png) [@c42f](https://discourse.julialang.org/u/c42f)\
**Post date:** [May 1, 2020, 3:12am UTC](https://discourse.julialang.org/t/non-friendly-documentation/38109/110 "2020-05-01T03:12:04Z")

</div>

> [@purplishrock](#):
>
> p.s. ok. i’ll stop.

Yes, let’s not derail this thread further (my fault for a silly post about git!) Just know that many experienced git users (including myself) still think it can be a cryptic mess, it’s not just you. The paradox of git is that it’s an extraordinarily simple and elegant data model wrapped in an extraordinarily complex interface. If you understand the data model you can put up with the interface though. Hang in there!

---

<div class="post-metadata">

**Author:** ![StefanKarpinski](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/stefankarpinski/32/24_2.png) [@StefanKarpinski](https://discourse.julialang.org/u/StefanKarpinski)\
**Post date:** [May 1, 2020, 3:42am UTC](https://discourse.julialang.org/t/non-friendly-documentation/38109/111 "2020-05-01T03:42:17Z")

</div>

This might help:

> **[Git man page generator](https://git-man-page-generator.lokaltog.net/)**
>
> Create an infinite amount of straightforward and readable git manual pages.

---

<div class="post-metadata">

**Author:** ![GregVernon](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/gregvernon/32/5611_2.png) [@GregVernon](https://discourse.julialang.org/u/GregVernon)\
**Post date:** [May 1, 2020, 4:49am UTC](https://discourse.julialang.org/t/non-friendly-documentation/38109/112 "2020-05-01T04:49:51Z")

</div>

Personally, I’d like to see more documentation of usage examples be “working” code and use `import` instead of `using`. Especially when coming to a new package, it’s often not clear what functions are a part of the package and what functions belong to another. When the docs use `using` you can’t immediately decipher where things are coming from.

Here’s an example of what I’m talking about from [IterativeSolvers:](https://juliamath.github.io/IterativeSolvers.jl/dev/iterators/)

```julia
A = sprand(10_000, 10_000, 10 / 10_000) + 20I
b1 = rand(10_000)
b2 = rand(10_000)
x = rand(10_000)

```

If you copy paste that example, the _first line errors with_  
`ERROR: UndefVarError: sprand not defined`

So the new user has to figure out: "what is sprand? It looks like a method `SparseArrays` would define (It’s actually also in `IterativeSolvers`, but the user can’t tell that from the example). So then the new user fixes the code:

```julia
A = SparseArrays.sprand(10_000, 10_000, 10 / 10_000) + 20I

```

which results in:  
`ERROR: UndefVarError: I not defined`

The new user, not aware of the existence of the `I()` method within `SparseArrays` / `LinearAlgebra` / `IterativeSolvers` then has to figure out “where did they set the value of `I`?”

Ideally, IMHO, this example should start with either

```julia
import IterativeSolvers.sprand
import IterativeSolvers.I
A = sprand(10_000, 10_000, 10 / 10_000) + 20I

```

or

```julia
import IterativeSolvers
A = IterativeSolvers.sprand(10_000, 10_000, 10 / 10_000) + 20*IterativeSolvers.I

```

Anyways, I’m picking on `IterativeSolvers` only because I think it’s a fantastic package, and I’ll go ahead and make a pull-request to fix this specific example. I just think that documentation is not the place for brevity in code examples - I think most new users prefer examples to be pedantic.

---

<div class="post-metadata">

**Author:** ![Tamas\_Papp](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/tamas_papp/32/25949_2.png) [@Tamas\_Papp](https://discourse.julialang.org/u/Tamas_Papp)\
**Post date:** [May 1, 2020, 5:41am UTC](https://discourse.julialang.org/t/non-friendly-documentation/38109/113 "2020-05-01T05:41:45Z")

</div>

> [@purplishrock](#):
>
> yes. it is that bad.  
> it’s very very cryptic  
> i find it hard to do simple things.

I am not going to argue that `git` is easy to learn — it isn’t. It is quite daunting.

But collaboration via distributed version control is an inherently difficult problem, and `git` is a very significant improvement on earlier version control solutions. A lot of the open source ecosystem (as we know it) simply would not exist without it (or a similarly powerful, presumably equally complex, and entirely hypothetical alternative).

Learning the basics of version control (which, nowadays, practically means learning git) is a very useful investment for anyone writing more than 100 LOC/week. It enables cooperation with others, and also has a lot of benefits for your own use.

---

<div class="post-metadata">

**Author:** ![ToucheSir](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/touchesir/32/14411_2.png) [@ToucheSir](https://discourse.julialang.org/u/ToucheSir)\
**Post date:** [May 1, 2020, 5:57am UTC](https://discourse.julialang.org/t/non-friendly-documentation/38109/114 "2020-05-01T05:57:24Z")

</div>

FWIW, I would kill to have something like [https://docs.rs/](https://docs.rs/). In other words, just having automated API listings with extensive hyperlinking between types/structs/functions in various packages (including the standard library!) can save a ton of headaches. For example, compare something like [tch::Tensor - Rust](https://docs.rs/tch/0.1.7/tch/struct.Tensor.html#method.leaky_relu_backward) to [NNlib · Flux](https://fluxml.ai/Flux.jl/stable/models/nnlib/#NNlib.leakyrelu). The former goes so far as to link to the `bool` documentation in `std`! This even applies to overloaded operators and re-exported symbols from other libraries, which seems even more relevant for the Julia package ecosystem.

All in all, I’m of the opinion that tackling low-hanging technical fruit such as this can at least provide a baseline of documentation without eating up too much maintainer time. Prose is great, but even seeing a (hyperlinked) list of what `Base` methods `DataFrame` specializes could save a bunch of time grepping through source code 🙂

---

<div class="post-metadata">

**Author:** ![tim.holy](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/tim.holy/32/52_2.png) [@tim.holy](https://discourse.julialang.org/u/tim.holy)\
**Post date:** [May 1, 2020, 9:05pm UTC](https://discourse.julialang.org/t/non-friendly-documentation/38109/115 "2020-05-01T21:05:05Z")

</div>

Do you see an advantage in this over, say, F12 in VSCode?

---

<div class="post-metadata">

**Author:** ![ToucheSir](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/touchesir/32/14411_2.png) [@ToucheSir](https://discourse.julialang.org/u/ToucheSir)\
**Post date:** [May 1, 2020, 10:10pm UTC](https://discourse.julialang.org/t/non-friendly-documentation/38109/116 "2020-05-01T22:10:27Z")

</div>

Yes, though I think they complement each other well. More specifically, I could `F12` all the way to something like `AbstractArray`, but VSCode doesn’t let me browse a package’s root level namespace.

Moreover, using something like definition-on-hover in VSCode requires adding any package you want to read the docs for. This is not a great workflow when one is trying to determine whether a potential dependency exposes some desired functionality. For example, I was looking through multiple MLJ and JuliaML packages today to decide a) which ones had classification metrics, and b) which of those were still maintained. Having to add a half-dozen packages just to do a symbol search for `f1_score` or the like feels unnecessarily onerous.

Perhaps this is personal preference, but I also find the tight integration of structured API docs and prose descriptions that you get out of something like RustDoc or JavaDoc makes for a far more efficient reference (e.g. [bool - Rust](https://doc.rust-lang.org/stable/std/primitive.bool.html#impl-Copy)). Documenter.jl does some of this, but doesn’t seem to enforce a dedicated API listing or automatic linking in rendered method signatures (e.g. what is `AbstractDataFrame` in [this Gadfly method](https://gadflyjl.org/stable/lib/gadfly/#Gadfly.plot-Tuple%7BAny,Dict,Vararg%7BUnion%7BArray%7BLayer,1%7D,%20Function,%20Gadfly.Element,%20Theme,%20Type%7D,N%7D%20where%20N%7D)?). If only there was a tool that integrated VSCode’s symbol/definition search, JuliaHub and Documenter.jl!

---

<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 2, 2020, 1:42pm UTC](https://discourse.julialang.org/t/non-friendly-documentation/38109/117 "2020-05-02T13:42:43Z")

</div>

I found the book by Demaree on git to be both accessible and helpful with understanding the whys of git.

---

<div class="post-metadata">

**Author:** ![Gus\_Hart](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/gus_hart/32/6987_2.png) [@Gus\_Hart](https://discourse.julialang.org/u/Gus_Hart)\
**Post date:** [May 4, 2020, 8:24pm UTC](https://discourse.julialang.org/t/non-friendly-documentation/38109/118 "2020-05-04T20:24:00Z")

</div>

Loved this whole thread. Thanks for 2 minutes tutorial. I’m going to try and contribute to documentation.

---

<div class="post-metadata">

**Author:** ![goodluck](https://avatars.discourse-cdn.com/v4/letter/g/65b543/32.png) [@goodluck](https://discourse.julialang.org/u/goodluck)\
**Post date:** [September 17, 2020, 8:45pm UTC](https://discourse.julialang.org/t/non-friendly-documentation/38109/119 "2020-09-17T20:45:49Z")

</div>

i finished reading the types section of the julia documentation [Types · The Julia Language](https://docs.julialang.org/en/v1/manual/types). it really, in my opinion, is quite bad. i appreciate that a great effort must have gone into making that chapter and i have really been trying to like it. but it plain simply is not a very attractive disposition; i believe it does not produce the kind of understanding and excitement in the reader that would correspond to the merits of julias type system; a system which really has great practical utility. that is a shame. the user should come out of reading with an urge to try out the neat features, which he understands, which he can see the practical utility from. as stated above, i think you should not underestimate the impact on user adoption from non-engaging and directly confusing documentation. the julia language by itself merits a _much__much_ higher growth rate than what i can discern has been the case over its lifespan, through google trends, redmonk ranking, tiobe ranking, general discussions. as it is now, big parts of the documentation seems like it was written by the writer to his audience of peers (who already fully understand the contents): to be academically solid, principled, “exhaustive”. the needs of the average reader are quite different. he needs examples, contextualisation via examples. he does not need abstraction nor completeness. not even when it comes to something like “abstract types” since, in fact, nothing is abstract about “abstract types”, they are just a different kind of animal, any bit just as practical as an Int64. the user needs to understand how this and that _works_ , again, via example, via sketch, via analogy. not via abstract musings. forza julia.

---

<div class="post-metadata">

**Author:** ![fredrikekre](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/fredrikekre/32/1688_2.png) [@fredrikekre](https://discourse.julialang.org/u/fredrikekre)\
**Post date:** [September 17, 2020, 9:05pm UTC](https://discourse.julialang.org/t/non-friendly-documentation/38109/120 "2020-09-17T21:05:03Z")

</div>

> [@goodluck](#):
>
> as it is now, big parts of the documentation seems like it was written by the writer to his audience of peers (who already fully understand the contents): to be academically solid, principled, “exhaustive”. the needs of the average reader are quite different. he needs examples, contextualisation via examples. he does not need abstraction nor completeness.

I mean, of course the initial documentation is (must be) written by, and reviewed by, people that understands it, and of course the result will miss the “beginner perspective”.

Since you just read through it you are right now (probably) the most suitable person to suggest changes and contribute to this section. We need people with your perspective to improve the documentation. As developers it is really difficult to know what parts are complicated, what parts need more explanation or examples. Tim even made a video to help new people (like you) get started with contributing: [Non-friendly documentation - #13 by tim.holy](https://discourse.julialang.org/t/non-friendly-documentation/38109/13)

---

<div class="post-metadata">

**Author:** ![goodluck](https://avatars.discourse-cdn.com/v4/letter/g/65b543/32.png) [@goodluck](https://discourse.julialang.org/u/goodluck)\
**Post date:** [September 17, 2020, 9:09pm UTC](https://discourse.julialang.org/t/non-friendly-documentation/38109/121 "2020-09-17T21:09:43Z")

</div>

yes in principle you are right, its people like me, beginners who can offer a good perspective on what is engaging or not, what is easy to grasp and what is not. unfortunately im not myself in a position where i can contribute. for now my very limited contribution is to just point out one or two things that may seem like details and pedantics to experienced folks, but which i think may actually, if not deter, fail to engage a significant amount of new-coming “customers”. thanks for listening and replying and thanks for the video, i will watch! forza julia.

---

<div class="post-metadata">

**Author:** ![Tamas\_Papp](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/tamas_papp/32/25949_2.png) [@Tamas\_Papp](https://discourse.julialang.org/u/Tamas_Papp)\
**Post date:** [September 18, 2020, 6:06am UTC](https://discourse.julialang.org/t/non-friendly-documentation/38109/122 "2020-09-18T06:06:12Z")

</div>

> [@goodluck](#):
>
> for now my very limited contribution is to just point out one or two things that may seem like details and pedantics

I read your post twice and I fail to find anything actionable or concrete there. With respect, I don’t think that vague complaints about the docs “not producing excitement” etc. help at all.

> [@goodluck](#):
>
> im not myself in a position where i can contribute

I am not sure why you think that. If you have an internet connection (presumably you do, since you are writing to this forum), you _can_ contribute.

But in any case, please kindly refrain from claiming that the documentation is “directly confusing” or has “abstract musings”. You may not want to contribute to it, and that’s fine, but disparaging the work of others who _did_ contribute to the docs without anything concrete or actionable is disrespectful and useless.

[Previous page](https://discourse.julialang.org/t/non-friendly-documentation/38109.md?page=5)

[Next page](https://discourse.julialang.org/t/non-friendly-documentation/38109.md?page=7)