Non-friendly documentation

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

an absolutely amazing language, world of packages, ecosystem of utilities, active community.

kudos to all the developers, documenters, maintainers, community participants, it really is amazing what you are creating. give me 10 years, no give me 20, perhaps 30, and i would not be able to create something like juMP, juliaDB, the parser, the compiler, juno, whatever.

all of this you give me for free. thanks a trillion.

and all of this deserves an equally amazing documentation to welcome newcomers, to discover the awesomeness of julia and all of what is has to offer the newcomer on a practical level. im truly sorry that i can not contribute myself beyond pointing out. consider that maybe im old, maybe im just a little resource-limited, maybe im just not so smart and better at criticising than constructing, even though the intention of my criticism is to be constructive.

so please dont take criticism personal. those who do have power to make change happen, consider that unfortunately there may be more people like me, hard of understanding. consider if their numbers and characteristics (are they perhaps scientists that really should be loving julia because it would be tremendously beneficial to them?) are such that you wish to make it easier for them to adopt julia?

but hey, maybe im wrong, maybe the documentation is 80% as good as it possibly can be and then there is no problem. but just maybe its only half as good as it could be. just consider it.

forza julia.

1 Like

For me, your ( @suharizen ) complaints are in some kind understandable (because I once was in a similar position) but still they clearly lack concreteness in the sense, that nobody can do something with it.

The topic “types” is not so easy to understand and the documentation on this topic is somehow on a high level. So I understand, that you can’t be very concrete in your criticisms or that you suggest concrete changes because for this you already need to have some understanding, BUT…

… please, try to say something, where others can go into action: For example you could formulate some questions you have, which you didn’t found answered in the documentation. Or point directly to some paragraphs, where you find it difficult to comprehend whats written or where you like to have a good code example to understand what this paragraph is about. This would be concrete enough and helpfull for better quality.

7 Likes

the problem is that, in my view, eg. the types chapter is only 25% as good as it could/should be. its wrong from beginning to end in “who is the reader” it addresses: who is the audience? it does not seem to be the newcomer looking for a practical understanding of how the bolts and nuts of types can make their life easier, make programming more enjoyable.

everything else follows from this premise, so it would be somewhat omsonst for me to be more specific. again, if the problem does not jump at you when reading, if nobody else has complained about this, then maybe its my problem alone. that is for others to decide.

let me also just say that i appreciate the arduous work of the people who wrote the current documentation. several hundreds of hours have gone into that. the language is polished and so on. thank you. im not criticising the writers effort, nor their intellectual ability. if anything, quite the contrary. at any rate hitting the right tune with your audience is terribly difficult since it is very hard to put yourself into the shoes of a reader very different from yourself.

a first step is to consider very deeply, who is my reader? maybe even, who is my, if not least-common-denominator reader, then at least who is my 10-percentile reader? how do i engage him? the primary newcomer-user facing documentation should be considered a funnel. more advanced, theoretical material is best linked-to in separate documents.

i have merely pointed out, “beware”, maybe there is an opportunity for a relatively quick win wrt user adoption in improving the primary newcomer-user facing documentation. think about it, that is actually good news. i think i can not be more concrete than i have already been. i think i will not be weighing in anymore about this topic.

forza julia.

1 Like

I think you’re right that the documentation can be improved to make it more accessible to beginners.

I think the big question is: “what is the action you personally are hoping will be taken in response to your comments?”

  • Are you hoping that others will acknowledge that the documentation could be better? Assuming people agree that you have a good insight here, is there a specific followup you’re expecting? On what timeline do you expect change?
  • Are you hoping that others will change the documentation in the ways you’re suggesting?
  • Are you trying to get people open to the idea of you changing it yourself?

Put another away: imagine hypothetically that the Julia community were run by an autocrat. What action would you expect them to take in response to your feedback? In the absence of new contributors to the community, improving the documentation requires diverting energy from other work. Which specific other work should be de-prioritized? Which people specifically should be moved between projects to staff up the documentation project?

I think the reason you’re seeing a gap between the reaction you might be expecting and the reaction you’re getting is that many readers likely assume you actually want an action to be taken in response to your feedback and are hoping you’ll do some work to help clarify a fleshed out action plan to achieving those results. Given that you’re asking for work to be done, it is fair to ask you to do some in return, no?

9 Likes

I don’t remember if it was already mentioned in this thread, but note also that resources devoted to improving Julia are relatively scarce, and usually people contributing to it (whether working full time on it or not) never lack ideas in how they can contribute (and are all aware that the documentation can be improved), i.e. free time is the limiting factor. Also, we can surely assume that the core devs know and thought about how a better documentation can increase language adoption. This is not to dismiss your remarks, but just to confirm that there are low chances that they will lead to concrete improvements (unless you engage your own resources).

Another point is that not everyone agrees with what documentation should look like (what is the main target audience, reference docs vs. tutorial-like docs, etc). This has already been discussed but AFAIK no definitive conclusion was reached in how this could be re-organized. At this point, an introductory book on Julia might be more fit than the official docs for people who would seek more beginner friendly material which “engages” the reader and tries to “make programming more enjoyable”.

2 Likes

My feedback on your feedback can only be:
It is probably true, same general guidelines can be read in books about good documentation, therefore it is not very helpfull.

I think that the current documentation is closer to a reference manual, than to a user’s manual. What is missing, IMO, is documentation that introduces Julia’s philosophy, provides extensive examples, and sort of ties together concepts that now are spread out in different sections.

There are attempts to write such a user’s manual in other websites, such as “learn X the hard way” or “wikibooks”. There are also published books, like “the little book of Julia algorithms”. Maybe those can help you more than the official docs.

Finally, a suggestion: if you don’t want to contribute to the official docs, consider starting a Julia blog. Write posts about what you found difficult to understand, or about exciting things you discover. There’s a website that aggregates Julia blogs, so others will discover yours. You can use Franklin.jl or Publish.jl to produce it and so, learn even more about Julia as part of the process. I know it takes a lot of time (I’ve been planning my own blog for more than a year now and I can’t find the time to start it). But it can be a worthwhile exercise.

4 Likes

You will find sections like that that later on (because more material needs to be covered for them), eg

https://docs.julialang.org/en/v1/manual/methods/#Design-Patterns-with-Parametric-Methods

You keep mentioning this, but it is not so apparent to me. The documentation can of course always be improved, but it is unclear that there are many low-hanging fruits that would magically increase adoption of Julia.

Eg splitting the Types chapter to a “newcomer” and an “advanced” part is quite difficult because many parts are interconnected. You would of course find out about this if you actually attempted a PR — all you need is a text editor.

great pointers, many thx!

I want to jump in and suggest that we channel all of this discussion into a working group. If you are interested in helping enable others to improve docs/improve docs yourself, please reach out to me and we can get a call/group started to take action on this stuff. I am all for good ideas and suggestions but in the end this is going to take some/all of us putting effort into this all to improve the current state of things.

(We have ML, GPU, Diversity, Community, and social calls right now so why not a docs call where we can talk meta docs and people can drive these initiatives!?)

13 Likes

thanks, that is a very good initiative and a nice invitation, to anybody. please forgive me that i do not have the possibility to participate myself. good luck to everyone, i am sure that it, or something like it, will succeed. even more so that julia will go through the roof, anyhow, eventually. forza julia.

I have been messing around with julia for about six months. The most difficult part for me has finding a reasonable explanation of how to something that lies between the newbie level and the grandmaster level.

Example: I recently had an understanding issue with dense arrays of structures. I got it working but I really don’t understand how it works. This worries me in that I may some hidden problem that will one day bite me.

The documentation often left me struggling to understand what I should be doing to accomplish a particular goal.

Often, there are too many ways to accomplish the same thing…the divide function blew my mind. Coming from other languages, I had certain expectations, especially when working with integers. I expected 3/2 to give me an answer of “1”, not “1.5”. Short circuit evaluations (something I think is a really good idea) seem to work/seem to not work (I have not taken the time to dig into the conditions).

Another one that confused me was interpolation using an array element. Example: arr = [1,2,3]

             str = "Array[1] = $arr[1]"  yields "Array[1] = [1, 2, 3][1]"  --- Not expected
             str = "Array[1] = $(arr[1])" yields "Array[1] = 1"  --- Correct

I just figured out that the second method was correct. A simple example in the docs might have saved me time and frustration.

3 Likes

I would like to point out that I found the Julia manual helpful when I started using it.
But in truth some of the things made sense only a long way down the road, and
some I skipped, at least initially.

In my opinion the manual blurs together the four kinds of user documentation, with attendant reduction in efficiency. In other words, the four “boxes”


are visited in this single document with little or no separation.

I personally try to follow in my own packages
the view of the sw documentation outlined here:
https://documentation.divio.com/ (I have no stake in this effort.)

I am sure the separation of the present documentation into tutorials, how-to guides, explanations, and reference would be a non-trivial effort. But I for one am willing
to help. Writing parts of the documentation is a great opportunity for
Julia users to learn the language better, IMO.

10 Likes

Great call out. Opened an issue here: https://github.com/JuliaLang/julia/issues/37646 and will address unless someone does before me.

2 Likes

Just wanna point out that the second paragraph in https://docs.julialang.org/en/v1/manual/strings/#string-interpolation documents this:

The shortest complete expression after the $ is taken as the expression whose value is to be interpolated into the string.

This might be an example where it is obvious to developers that write the docs what it means but beginners might need an additional example.

5 Likes

Great call out, I think this can be resolved by adding an example there.

I concur–it was not obvious to me that () was needed to access an array element. My assumption was that the compiler would recognize that arr was an array and therefore require an array index. Bad assumption.

A two liner example could save someone a lot of grief.

Thanks.

@mbaz thanks for this pointer https://scls.gitbooks.io/ljthw, “learning julia the hard way”

@PetrKryslUCSD a tutorial, a primer.

it certainly was not hard, but rather very enjoyable. i read it in one fast slurp. there was not a thing i had to re-read, everything was so construed as to make the reader feel clever and in the know; leading him up to a sufficient level of understanding for him to want to start his first script/program; to dig in with advanced topics as the need will present itself in the future; bestowed with enough of an initial vocabulary and a roadmap to explore further.

within docs.julialang.org a similar tutorial/primer could link to a practical (not overly technical) reference manual, similar to the current one, but with improved pedagogy: still aimed at the average or below-average reader (wrt patience or proficiency if you will), aimed at conveying how the more advanced material is of practical utility. ideally, the reader, with a modicum of interest, should be able to capitalise on and convert every tidbit into an improvement of actual or future code => cleaner, shorter, faster, safer, more scalable code, etc.

let users fall in love with julia, you all deserve that. the users deserve that. the world deserves it. everybody will eventually, anyhow, but no harm in accelerating it a bit. maybe the writer https://scls.gitbooks.io/ljthw is already collaborating with you, if not, maybe he could Chris von Csefalvay