First-contributions: [discussion] restructuring the guide for better clarity

[kevinnls]

a discussion to improve structure of the guide by mapping out the objectives of the guide at the beginning and at the end, linking explanations of all steps undertaken in README.md, etc.

---

🐞 Problem

• the guide is on point about steps to follow
• however
  
  
  
  • does not provide a clear idea of objectives
  
  
  • does not explain whatthegitjusthappened i.e. what happened with each git/GH command
  
  
  • does not explain good practices outlined in guide
  
  

🎯 Goal


when i made my first contribution here (#26492), it was all quite murky. confused what happened for the most part; especially with regard to why i had to create a branch add-<name>. this question has been a repeated often, most recently at #309555. there is a separate doc explaining why branches, but hidden away with no obvious hyperlinks to it.

so the goal would be to provide the contributors with pre and post-git clarity.

"one to serve as a torch to wade through the waters;
the other as floodlight to look back and understand the waters they've crossed over."

---

💡 Possible solutions

1. the torch: outline the steps (and subsections?) of the contribution process at the start

e.g:

To reach the objective [of making a contribution] we will:
1. Make a copy of the project
2. Modify the copy
3. Combine the copy and the original

1. the floodlights: add a section at the end of the guide - whatthegitjusthappened

   • this will link to a doc which shows and explains the steps that contributors went through during earlier
     
     
     
     • question of: CLI and GUI? - how explain both? or separate?
     
     
   • this will be separate from additional-materials.md
2. uniform alignment of pictures (illustrative screenshots)

[kevinnls]

@Roshanjossey and community, please take a look

[ayush-wilfred]

I completely agree to what you just stated.
Even I was too confused what's the function of these commands.

We can also add links refers to the proper function of commands.

[Roshanjossey]

Thank you for creating this issue @kevinnls.

I'll share some thoughts about Problem and have a discussion then talk about solutions.

does not provide a clear idea of objectives

I don't think this is a problem. I think the tutorial is short enough not to have an overview. The 6 steps (fork, clone, branch, change, push, submit) is already short. I don't think a lot of people are confused about the objectives and adding an overview would help.

I think we should find a way to get data from our users to understand if this is really a problem. I get feedback as comment on pull request and I've not had this feedback yet. However, those comments are by people who successfully went through the tutorial. I don't have any feedback from people who came here and didn't go through the tutorial.

does not explain whatthegitjusthappened i.e. what happened with each git/GH command
does not explain good practices outlined in guide

I agree that these are problems worth solving. Explanations might not be useful for everybody but for the people who wants it, it should be easy to find it.

[kevinnls]

I think we should find a way to get data from our users to understand if this is really a problem.[...] I don't have any feedback from people who came here and didn't go through the tutorial.

i could try asking some friends who haven't contributed to OSS yet and are at varied levels of git expertise to try the guide and add their comments here. would that work for now?

[Roshanjossey]

Would it be possible for them to have us on a video call while going through the tutorial or record it.

We haven't done any user testing for almost four years. The closest to that we had recently was https://www.youtube.com/watch?v=ZJy_fIDrVmQ

[kevinnls]

Would it be possible for them to have us on a video call while going through the tutorial or record it.

Discord sound good?

[Roshanjossey]

Sure, works for me

[kevinnls]

hi @sarveshh thank you very much for making the PR
but this is actually still a discussion. we have not yet decided which parts of it to implement; but we'll definitely use at least some (if not all) of the work from your PR after we've decided on how to go about the whole thing, so please hold on until then :)

PS: @roshanjossey or @sara-02, could you please add the discussion label?

[kevinnls]

@agashvaran and @Mckenz31 thank you for participating in the user review last week. on the basis of your experience following the guide, do you have anything to refute / support / add to in the changes proposed?

your contributions are welcomed!