Looking over the recent discussion about improving docs, it’s clear that people find issues they could fix with the docs but don’t necessarily open issue/prs to fix them. Is there something we can do here? First, we should understand why people don’t contribute. Is it
git panic? The github contribution model is certainly intimidating at first. There’s videos and tutorials on making first prs but people might not want to bother (although at that point making prs is somewhat of a life skill for people interested in IT) github recently hugely improved the process, to the point that fixing an issue can be done just on the web interface, without need for manualy creating and maintaining a fork. But perhaps people don’t know that? The buttons to do it are kind of hidden.
the huge number of open issues and prs on the git repo that’s putting people off contributing because they assume their contribution will just be ignored? That’s not been my experience, but some contributions certainly fall through the cracks
the fear of contributing in public to a large project?
the feeling that making a one character pr is not worth the bother?
plain old laziness?
If it turns out to be a combination of the above factors (minus the last one, which we can’t really do much about), something that could be done is to setup an unofficial buffer repo that would be a fork of the main one, but with a more friendly design (a Readme outlining the steps for contribution, no ci, a small number of open issues/pr, everybody who asks gets right to review / merge prs, etc). Then once in a while Somebody With Git Skills ™ syncs it with the main repo by making a PR with a large number of pre-filtered small changes (which is easier for people in the main repo to review and merge). I’m not sure if it’s a good idea or just a maintenance headache that will not actually be useful to anyone. What do people think?
git panic? Yes, knowing a little git and had an account but still felt insecure about doing something wrong and had never really used it for PRs/issues but mostly for storing personal projects. After the first few PRs this mostly disappeared.
I don’t think this was ever any concern for me.
Yes. Maybe a little less after the first few PRs, but I still find myself a bit nervous about making something obviously stupid…
Yeah, still can feel this but have done it a couple times.
Yeah, if there is actually a problem I usually at least open a quick issue if I don’t have the time to fix myself, but if there is mostly something tiny in the documentation I often will just leave it be and assume someone else will fix it at some point.
I don’t think a buffer repo would have made any difference for me. What did help for me was people in the community encouraging and helping. But other people might be different here.
the huge number of open issues and prs on the git repo that’s putting people off contributing because they assume their contribution will just be ignored? That’s not been my experience, but some contributions certainly fall through the cracks
My experience with code reviews in general, not specific to Julia, is that multiple independent small PRs are easier to review than one large PR. Especially if you get a PR with 9 obviously fine changes and 1 change that is problematic for some reason, the good ones will be stalled and add to the cognitive burden of getting the last change into a good state. Merging is rarely a factor compared to reviewing, usually just pressing a button.
(Occasionally 1 small PR might be preferable to 10 tiny ones though, depending on what’s in there, and lighter on CI.)
Probably we need to add simple Contributing information for the “Getting Started” part.
or
we can extend the “Documentation” part with “Fixing/Improving Julia documentation”
2.) maybe we can add an “Edit/Improve this section”-icon everywhere - linking to the source Github pages.
It may also be interesting to highlight issues where contributions should be easy, for instance by adding a link to the filtered list of “good first issues”
I think that is good if someone has passed the “git fear”, but I would already be happy if someone noticing a mistake in the docs or seeing some improvement first even opens an issue.
To the general topic, after a few PRs that grew really large, I am also becoming more and more a fan of small PRs, which would also be nice for people that start.
All points mentioned above are valid, I may add less-than-perfect English. My own experience with the only documentation PR I have tried (on an not especially important point) was that I got a pretty unfriendly reply - I hope that was an exception, but that was it for me. In any case, the threshold especially for novice users is here, it is pretty high, and not going to disappear.
Good documentation costs money as a rule. Writing documentation is not as exciting for most of us as programming, that’s why there are that many greatly written but poorly documented open source packages out there.
In short - if there were money (or an equivalent incentive) for that, than having one person responsible for transforming rants, errors found, ideas etc, discussed here and elsewhere into PRs, issues etc. could help. Like the current community manager, but dealing with such low-level things.
@jishnub you should bump that more frequently. reviewers often go through cycles of ignoring emails for a while then getting back to them, so you have to get them when they are paying attention to that particular area
When asked to make a documentation Pull Request, I would think you would start in the Github “Pull requests” tab and click the big green “New pull request” button. You don’t.
The way to edit the documentation, is to dig around the “Code” tab until you find the file with the section you want to edit.
If you are able to find the right file and the pencil edit button (and also don’t get scared away by the word “Fork”), then you make it to the next section.
Markdown and Documenter Syntax
You are now editing a markdown file in place on Github which is not a great experience.
There is no spell check, so you need to copy and paste from another editor.
There is no syntax highlighting in code blocks, so you need to copy and paste from another Julia session.
There is no side-by-side preview, so you have to switch back and forth between the Edit and Preview tabs to check your Markdown syntax. Every time you switch tabs, you have to scroll all the way down to the section of interest again.
Documenter links (@ref) do not show up in the Preview, so you are just guessing if those are going to work.
I found that actually making the fork and editing in VSCode helps with most of these issues, but a.) the hurdle to get there is large, b.) I still don’t know how to test Documenter links, c.) it adds to the fear of making mistakes.
Fear of Contributing in Public
I had a big fear when I started that I was going to accidently break something. “Open source” lead me to believe that I was actively editing the code on Github, so I didn’t want to touch anything and break it. I now know there are safeguards in place, but digging around source code is still difficult and scary.
You are going to make a maintainer sift through your submission and hope they catch your mistakes. I think mistakes are inevitable on your first several contributions, and some people may be unwilling to make those publicly for fear that they are being more troublesome than helpful.
Subject Knowledge
When do I know that documentation is deficient; it is when I am searching for information that isn’t there. I am likely not reading documentation on topics with which I am already familiar.
I will often submit an Issue that documentation is lacking and then be told I should submit a PR instead, but I don’t have the knowledge needed to generate it. The question is when do you have enough knowledge to write documentation?
When you get your first working answers on Discourse or StackOverflow? Doubtful that you can write something in context of the larger API at that point.
When you have used some package function a couple different ways? My personal answer.
When you have read and understood the source code? I am usually not capable of doing that, but it would be better.
If there is no documentation on something and you are not a good enough programmer to navigate the source code, then you are just guessing at how things work through trial and error. I don’t think my best guess is a great foundation from which to write official documentation. The best documentation comes from a newbie and an expert working together, but how do you facilitate that interaction without being annoying?
I’ve made a few documentation PRs, some even merged. I find the “edit on github” button super useful because it is a very low entry bar. But then for doctests, it’s a annoying that I can’t run a small quick test to see if my change works. I had a recent one that worked in the REPL, but failed as a doctest due to different escaping rules. The next issues I’ve run into is people will ask for work that is impossible through the edit “edit on github” interface, eg I’ve been advised to build docs locally to see how they render. I know it was meant as a helpful comment, but it felt like I was invited to help via “edit on github” in a low stakes way, then immediately the stakes up increased. Finally, tests. Tests take a long time, so there is very slow feedback for even very small changes, and there are random test failures and test info overload. My most recent PR (the first link) is has failing test, at least some of which are unrelated to the PR. I’m not interested in going through every one to try to confirm.
Based on that, I suggest to have a special documentation only PR mode. Maybe it’s indicated by a flag like some github integrations I’ve seen like #EZDOCPR and that’s auto inserted by “edit on github” buttons. Other responders are made away the submitted is interested in helping, but less likely to be interested in upping the technical stakes, like building locally. It should run a SINGLE FAST test that only runs doctests in edited file, maybe even submitting it to a currently running julia master instance, so it skips all the downloading and compiling and whatnot. And it doesn’t generate any notifications to other github users until the quick tests pass. It doesn’t feel great when you submit a doc PR and it fails due to some formatting things and you know it’s pinging people or at least showing up in the issue tracker like, it can feel like a big flag saying “hey I’m bad at this”.
Great summary! I just want to add that for people who do not necessarily have VSCode set up, github.dev can be a good alternative for simple Markdown editing tasks. Unfortunately, its very existence seems like a well-kept secret, so maybe we should redirect new users to it instead of the native GitHub editing interface
OK, the help for new contributors is split between Contribution Pathways (which is linked to in the bottom of the home page, not very visible; generally speaking, the structure of the webpage is pretty weird, with both a menu on the top and one on the the bottom) and julia/CONTRIBUTING.md at master · JuliaLang/julia · GitHub. CONTRIBUTING.md is linked to from the homepage, but the link is hidden (it’s the only non-bold thing in a sea of bold). Both documents are pretty technical, the two don’t reference each other, they are pretty long, they mostly address code PRs, and don’t address github workflow issues and etiquette (for instance @jameson 's suggestion of pinging back at reasonable intervals). There could be a short “we welcome contributions, both code and docs, both issues and PRs, PRs are easier than it sounds, don’t worry about breaking stuff, here’s how to make a PR with github’s simplified interface if you don’t know git, here’s how to make a PR with the full github workflow if you do, feel free to ping back every couple of weeks if there is not reply, here’s where to ask for help, here’s more extensive info (link to CONTRIBUTING.md)”, but I’m not quite sure where to put it, and whether/how to change the existing info (to avoid the xkcd: Standards syndrome)
