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

fineanmol commented 2 years ago

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.