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 .
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.
finds documentation really confusing. Wonders why people can’t write decent documentation. Does not feel comfortable contributing by filing problem reports or fixes, on the grounds that s/he does not yet understand enough about the package to make a meaningful contribution.
struggles a lot but eventually figures it out.
moves on. Notices someone else struggling with the same package. But doesn’t help out, because isn’t motivated to put time into improving the documentation since by now s/he understands the package and doesn’t need the documentation.
This is an incredibly costly cycle (the number of wasted hours are huge), but I don’t know how to break it.
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:
Prior experience required to work with doc-tools (Documenter.jl, what else?), examples, tests and so on.
A number of user actions (N) needed to be done in order to contribute into a package doc. Optimally, 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:
Make a local copy of a package in dev.
Make a separate branch.
Find where docs are generated, add new examples.
Check if they look OK.
Cover docs examples with tests.
Make a PR.
Fix some problems with that PR.
…What else did I miss?
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.
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.
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
sometimes the person who created something is not the best person to introduce it to a newcommer
writing documentation is not easy, and people who are good at coding may not be good at documenting (and vice versa)
to anyone who feels annoyed that the documentation is bad (and it often is): keep in mind that most code is posted for free. If someone gives you one present, it’s not fair to ask for a second present. It’s great if they give it freely, but contributing docs is a way for the entire community to repay the generosity of those who donated their time to write & maintain the code.
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.
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.
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.