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.
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.
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.
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?
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â.
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.
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.
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!?)
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]
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.
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.
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 Introduction ¡ Learn Julia the Hard Way is already collaborating with you, if not, maybe he could Chris von Csefalvay
