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 
7 Likes
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.
16 Likes
Come on, it’s not that bad. As far as I know, git’s actions are always undoable.
2 Likes
Yeah but it’s not always easy to undo them.
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
8 Likes
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 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.
4 Likes
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.
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!
2 Likes
This might help:
13 Likes
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:
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:
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
import IterativeSolvers.sprand
import IterativeSolvers.I
A = sprand(10_000, 10_000, 10 / 10_000) + 20I
or
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.
11 Likes
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.
2 Likes
FWIW, I would kill to have something like 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 to NNlib · Flux. 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
3 Likes
Do you see an advantage in this over, say, F12 in VSCode?
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). 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?). If only there was a tool that integrated VSCode’s symbol/definition search, JuliaHub and Documenter.jl!
1 Like
I found the book by Demaree on git to be both accessible and helpful with understanding the whys of git.
3 Likes
Loved this whole thread. Thanks for 2 minutes tutorial. I’m going to try and contribute to documentation.
5 Likes
i finished reading the types section of the julia documentation Types · The Julia Language. 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.
2 Likes
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
8 Likes
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.
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.
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.
10 Likes