Is it my idea or many libraries assume a huge amount of pre-knowledge in their documentation.
For what I have seen until now, many libraries that are wrappers or reimplementation of other libraries in other languages the documentation goes a little bit like this:
“It works exactly the same as in language XXXX but the syntaxis is completely different so you have to do it the Julia way.”
And that’s it.
Have anyone else struggle with this problem? How did you overcome it?
I have struggled with this problem and usually what I do is clone the library from github to my machine so I can search it. So in one monitor I have my code, in the second I usually have the source for the julia library I’m working with, and in the third I have the documentation of the library. Sometimes I even have to bring down the source for library written in the other language…but I don’t have a monitor for it 
.
File an issue. It’s difficult to know what others don’t know.
Some may be very well documented, and some very poorly. Developers may be focusing their efforts in making the library work before documenting them properly. Perhaps they are work in progress, and documentation is still TBD (the majority of Julia packages are still labelled as v0.X.Y).
The best way to overcome the problem is that users who have managed to use those libraries contribute to documentation with their own examples. If you have interest in some specific package, but you cannot help documenting it yourself because you just don’t understand how to use it, you could try here to look for more people sharing your interest, and maybe organize a coordinated effort to create such missing documentation.
Here’s a very common trajectory:
This is an incredibly costly cycle (the number of wasted hours are huge), but I don’t know how to break it.
Agreed. I have certainly followed that path a number of times.
Breaking the cycle will take some brainstorming, so let me begin with some ideas:
Interesting ideas!
Encourage package authors to set up a “page” with user-supplied tips&tricks.
I’ve set up links imploring users to provide feedback (e.g., Home · JuliaImages), and we have a call for demos, but there are very few takers.
Have a workshop/coding session on JuliaCon where the aim is to make PRs of “first-steps tutorials” for n number of packages.
I like that! I often suspect people see hackathon and they think code, maybe we need some community docathans.
Give out a community price for people who contribute material like this.
The “big” community prize strives to recognize more than just code, and people have won for contributions to adding documentation & tests (The Julia Community Prizes, 2018) and for teaching & outreach (JuliaCon 2019, Baltimore, MD, USA). But there are so many contributors to the ecosystem that big awards necessarily recognize only a few superstars among many.
It would be nice to have a way to recognize the “ordinary,” “awesome,” and “superstar who just happened not to win (yet).” Any ideas how to do this?
I have a lot of sympathy for the preceding comments about the challenges of implementing helpful documentation, which is not easy at any point.
I would say for me that one “barrier” is that I’m no expert in setting up a PR (i.e., I’ve never done this). I often think, boy I have a great idea to make this more clear, but then I think - ah, now I have to do some research to figure out this PR thing (no rocket science, but I’ve got lots to do…).
If there were some more immediate approach that might help lower barriers.
I think , there are two barriers for users making better docs:
N <= 3: open input form – wirite or paste text – confirm.To address #1, there should be simple videos like “how to improve docs in 5 minutes?”, similar to this.
To address #2, there should be some simplified tools that automate making proposals to the docs, based on user actual behaviour when he or she tries to fix errors or learns new packages. Usually I learn new packages into separate .jl files and then use them along with reference docs, when I need to remember or reuse something.
So, there are too many actions needed to convert some jl scripts – into an approved PR. How it is done now:
Hypothetical shortest paths (one or two simple actions required from user):
a. Automatically convert discourse solved questions into FAQ examples attached to packages? Or just have a list of links at the end of the docs.
b. Add some user-input form, embedded into docs, so user can just copy-and-paste his proposals and code in arbitrary place, then convert it to an automatic PR. Just like sidenotes: “nope, this is not working, better use this: …”, that can be added into main text.
But why can’t we have documentation as the one in numpy? Many documentations fail to have a list of their functions and what type of parameters it should have.
The problem is that the overlap between the group of people willing and able to write good code and the group of people willing / able to write good documentation is small.
If you’re willing to go into some packages and open PRs to add better documentation, you’d have my support for sure.
Numpy’s been around in one form or another since 1995, while many Julia packages are less than five years old. Julia’s performance is delivered by LLVM, which existed for nearly a decade before the language itself, but there’s no similar shortcut for thorough documentation. The core language and large packages are well-documented, but technical writing takes time and effort that often goes unrewarded. Unless that work is compensated (whether monetarily through GSOD or through prestige), it’ll go slowly if at all.
To address #1, there should be simple videos like “how to improve docs in 5 minutes?”, similar to this.
Like this? https://youtu.be/ZpH1ry8qqfw. And it’s only 2 minutes 
But why can’t we have documentation as the one in numpy? Many documentations fail to have a list of their functions and what type of parameters it should have.
The amazing Documenter.jl automates that process, so people who use it can have an API page. Example: Home · FlameGraphs.jl (click on the “Reference” page for the info you were asking about).
So the answer is, we can, it just takes people willing to contribute. Sometimes people expect the main programmer to contribute the docs, and many do, but
Yeah, it’s a rather arcane process until you get used to it. Fortunately, Github has actually done a lot to make this easier than it used to be, particularly for changes to things like documentation. Try going to any github source page (e.g. https://github.com/JuliaImages/Images.jl/blob/master/README.md ) and clicking the pencil icon in the upper right of the text area. You’ll get a web editor to edit the text, and it will automatically help you create a PR to submit your changes when you’re done.
The overlap is equal to the group of people willing and able to write good documentation, right? 
Yes, it is probably small!
Following up on this, Documenter places that “Edit on GitHub” button at the top of each page. It takes you the markdown file which you could then potentially make the changes you wish and submit a PR. This would work ok if you were changing some sort of “explanation” or descriptive text. A shortcoming is that it does not work if the stuff you want to change lives in a docstring, as that resides with the code in a separate file.
True, but at least you can use it to post a comment. Obviously it’s much more helpful to fix the problem, but any means of communication is better than nothing.
Oops! One of those was supposed to be code, not documentation 
. Edited.
I almost never go to a video - I’m too used to scanning the written word to find the information I need. Maybe I’m too old school, but I’d like to be able to just skim for relevant terms…
This is useful to know - for what it’s worth my organization (kinda small) only keeps one master branch and there is no curation of changes, which makes things interesting some times… and it also creates another disincentive for me to learn the PR
I’ll try to follow your suggestion, as I do have a couple documentation issues noted and even gave myself a reminder to submit a PR for one of them - just need to get over the proverbial hump.