Skip to content

Design decisions for the tutorials (Please read this before suggesting changes) #35892

Open

Description

@Roshanjossey

This is not an issue, but more of a documentation of the design choices we made for the tutorials and what we learned from community feedback.

1. Keep the tutorial short

I think this is one of the most important aspects that helped this project grow. Getting a pay-off within five minutes of learning something is remarkable. For brevity, we have to compromise on details. A lot of details are missing from the main tutorial. From explanations on what actually happens when you run those commands to other good practices one could follow.

2. Accessibility matters

We want these tutorials to be accessible to as much people as possible. Be it somebody having trouble with language barriers or someone with limited internet speed. Translations help people understand this in languages they're more comfortable with. Keeping the size of this repository small will help with limited bandwidth.

3. Contributors.md doesn't matter

This is one point where I had multiple discussions with the community. Contributors list exists just as a file you can edit to work through the tutorial. How it looks or what you add there doesn't matter. We'll remove most entries in it from time to time because we don't want someone being left out because their text editor can't open a huge file.

4. Be generic.

We could make assumptions about what OS most of our users are using or what terminal emulator or text editor they're comfortable with. By not making such assumptions, we give our readers more freedom and include more people.

Feel free to challenge any of the above in the comments. I'd love to get feedback from you. Let's have a discussion.
Also, there are things I'm struggling to design. Like how to give directions to proceed right after one finishes the tutorial. So, comment down below what you're looking for right after you finish the tutorial and what you're missing.

Activity

  1. self-assigned this
    on Jan 5, 2021
  2. pinned this issue on Jan 5, 2021
  3. unpinned this issue on Mar 7, 2021
  4. pinned this issue on Mar 20, 2021
  5. sambhavsaxena commented on May 11, 2021

    @sambhavsaxena
  6. peterthankgod commented on Apr 3, 2022

    @peterthankgod
  7. johan237 commented on Apr 21, 2022

    @johan237
  8. sambhavsaxena commented on Apr 22, 2022

    @sambhavsaxena
  9. pichpeyman commented on Sep 29, 2022

    @pichpeyman
  10. Mihails79 commented on Aug 9, 2023

    @Mihails79

    None

  11. asterdoescomputing commented on May 15, 2026

    @asterdoescomputing
    Contributor

    Okay yeah, Contributions.md doesn't matter, but what if we could just make it look more beautiful, allow users to add their profile pics and make it more lively :)

  12. Pallavi-vi-1234 commented on May 26, 2026

    @Pallavi-vi-1234
    Contributor

    Hi @maintainer,
    I would like to work on this issue under NSoC 2026.
    Can you please assign it to me?
    Thank you!

  13. SRamkumar190 commented on Jul 18, 2026

    @SRamkumar190

    Hi! I'm currently working through the tutorial as my introduction to open source, and I wanted to share some feedback from a beginner's perspective.

    I really appreciated how short and approachable the tutorial is. Being able to make my first contribution in a short amount of time made the process much less intimidating.

    One thing I think could help after completing the tutorial is providing a small "What's next?" section that recommends a few beginner-friendly open-source repositories (organized by language like Python, Java, JavaScript, etc.) along with advice on how to find a good first issue. That would make it easier for new contributors to transition from the tutorial to real-world projects.

    Thanks for maintaining such a great resource!

  14. Roshanjossey commented on Jul 19, 2026

    @Roshanjossey
    MemberAuthor

    Hi @SRamkumar190, could you describe your user experience after you finished the tutorial?

  15. kyraa-up commented on Nov 20, 2026

    @kyraa-up
    Contributor

    Hi! I just completed the tutorial and had my PR merged. I’m a data science and psychology student and this was my first open source contribution.

    What worked: the steps were short and easy to follow, and I got through fork, clone, branch and PR without trouble.

    Where I got stuck: my PR showed “Can’t automatically merge” because many people add their name at the end of Contributors.md at the same time. I didn’t know this was normal. Some lines in that file also contain leftover conflict markers (<<<<<<< HEAD), so GitHub’s conflict editor looked confusing. I ended up syncing with upstream, resetting my branch, re-adding my line and force-pushing, which I only managed with outside help. I also got “Auto-merge PRs workflow failed” notifications and wasn’t sure whether I’d done something wrong.

    Suggestions: (1) add a short note saying conflicts at the end of the file are common and what to do, with a link to the conflict guide; (2) add a “What’s next” section. I agree with the earlier suggestion, and for people from data science or research backgrounds it would help to include a short list of beginner-friendly Python and science repos and how to find “good first issue” labels.

    Thanks for maintaining this, it was a really great starting point for me.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions