Lowering the bar for beginner contributions

Community
12

Git Panic

  1. 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.
  2. 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.
  3. 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.

  1. There is no spell check, so you need to copy and paste from another editor.
  2. There is no syntax highlighting in code blocks, so you need to copy and paste from another Julia session.
  3. 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. :triumph:
  4. Documenter links (@ref) do not show up in the Preview, so you are just guessing if those are going to work.
  5. 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

  1. 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.
  2. 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?

  1. 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.
  2. When you have used some package function a couple different ways? My personal answer.
  3. 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?

18 Likes