"Clone the repository" instructions in README.md to include folder option

[ketansahugit]

Update "Clone the repository" instructions in README.md to include folder option

🐞 Problem

The current "Clone the repository" instructions in the README.md file do not provide clear guidance on how to clone the forked repository into a specific folder. This lack of clarity can cause confusion for new contributors who want to set up the project locally.

🎯 Goal

The goal of this issue is to update the "Clone the repository" instructions in the README.md file to include explicit steps for specifying a folder when cloning the forked repository. By providing clear instructions, we can improve the user experience and make it easier for new contributors to get started with the project.

💡 Possible solutions

One possible solution is to add a new subsection under the "Clone the repository" section in the README.md file. This subsection can provide step-by-step instructions on how to navigate to an existing folder or create a new folder before running the clone command.

📋 Steps to solve the problem

• I have already raised a pull request #<70000> that addresses this issue. The pull request titled "Updated 'Clone the repository' instructions in README.md to include folder option" contains the necessary changes to the README.md file. Please review the pull request for further details.

Thank you for your attention to this issue. If you have any questions or need additional information, please let me know.

[Roshanjossey]

@Esh07, I'm interested to know your thoughts on this change. Could you please comment here or add a review on the linked PR?

[Esh07]

Hey @ketansahugit, thanks for proposing this improvement.

I think it’s important to keep the tutorial simple enough for beginners. The proposed changes by @ketansahugit work.

The changes look on point and it does make sense. 👍🏼

@Roshanjossey Should we keep documentation at the absolute beginning for bash/terminal beginners?

[ketansahugit]

@Esh07, you are correct. The documentation should be easy to understand for newbies. I actually faced a similar problem when I was new to using the terminal and had to spend some time looking for the cloned repository. With the proposed changes, the user can specify where they want the repository to be cloned, making it easier for them to find and open the repository in their desired code editor, such as VS Code. This improvement will definitely enhance the user experience.

[Esh07]

@Roshanjossey I propose these changes which I think is sufficient and concise. What your thoughts on it?

[Roshanjossey]

@ketansahugit, from your comment, I understand that the real problem is that users might not know where cloned the project to. This gives them a hard time when they have to open the repo in a text editor. Is this correct or are there any other aspects to the problem?
Also, could you tell us how you solved this problem and how much time it took for you?

@Esh07, In your suggested changes, you don't have the create directory step. Instead, you went with the other option suggested by @ketansahugit in Possible Solutions section

This subsection can provide step-by-step instructions on how to navigate to an existing folder or create a new folder before running the clone command.

What's reasoning behind this?

[ketansahugit]

@Roshanjossey That's correct. To find the cloned file, I tried various approaches such as checking major folders, but they didn't have recent time modifications, making it difficult to locate the cloned project. Eventually, I resorted to a Google search. The initial few links were unhelpful, but I discovered that I needed to check the C drive. Specifically, I found the project in the Users folder within the C drive. It took me approximately 45 minutes to find it.

Regarding the suggestions provided by @Esh07 , I am okay with them. I appreciate the feedback and would like to hear your views on the suggestions so that I can make the necessary changes in my pull request.

[Esh07]

@ketansahugit, from your comment, I understand that the real problem is that users might not know where cloned the project to. This gives them a hard time when they have to open the repo in a text editor. Is this correct or are there any other aspects to the problem? Also, could you tell us how you solved this problem and how much time it took for you?

@Esh07, In your suggested changes, you don't have the create directory step. Instead, you went with the other option suggested by @ketansahugit in Possible Solutions section

This subsection can provide step-by-step instructions on how to navigate to an existing folder or create a new folder before running the clone command.

What's reasoning behind this?

I did mention creating a new folder. It might be hard to read because it’s toggled.

So far, what I understand is that the problem is about cloning the repository to the wrong places which new users might face issues finding. However, if we look at the documentation, it clearly says:

If you’re not comfortable with the command line here are tutorials using GUI tools.

What I think is that we can add a note saying “Change the current working directory to the location where you want the cloned directory”.

I also want to add something. The documentation already explicitly states that it is for those who are comfortable with the command line. As for “cd”, we can expect that they know how it works or where to change the current directory to their preferred one. If that makes sense.

[ketansahugit]

I think my changes make it obvious what users need to do, especially for command line users, and it wouldn't hurt to add them. They only make the documentation more explicit and are straightforward and helpful.

[Roshanjossey]

I understand is that the problem is about cloning the repository to the wrong places which new users might face issues finding

I have a different opinion, the root problem is that the user is not familiar with command line. @ketansahugit has already mentioned it.

I actually faced a similar problem when I was new to using the terminal

If user is familiar with CLI, they can figure out which directory they're in by using commands like ls, pwd (or corresponding commands in windows)

The problem with the suggestions to solve this is to add another command to execute. That's another step. Another point of failure.

I'm not saying somebody who's not familiar with CLI shouldn't follow the main Readme. More power to the people who wants to learn and explore. But we shouldn't optimise for that. We should optimise for the general case. They might need to learn about CLI by themselves in that process but that's a good thing.

I think my changes make it obvious what users need to do, especially for command line users, and it wouldn't hurt to add them. They only make the documentation more explicit and are straightforward and helpful.

It could hurt. It could make the experience worse.
There's a lot of things we could add to the tutorial. Like setting up git config, using git add -p instead of git add Contributors.md etc. You could argue all of this makes the documentation more explicit and helpful but they also makes it longer and adds more steps.

One thing that works well for this tutorial is that it's short. That's achieved by getting rid of helpful steps that are not important to the PR flow.

My suggestion is not to change Readme to fix this.

Rather, we could add to #30831 to help other people who might face the same problem

[ketansahugit]

@Roshanjossey I will add this to #30831. Additionally, I want to highlight that many beginners tend to skip reading the entire Readme file and start following instructions from the beginning. I must admit, even I wasn't aware of the tutorials using different tools guide; otherwise, I would have preferred the VS Code tutorial. To assist newcomers, could we consider moving the tutorials using different tools section closer to the top for better visibility? Thank you for considering this improvement.

[Roshanjossey]

Thank you @ketansahugit.

We have this line on top of the Readme file

If you're not comfortable with command line, here are tutorials using GUI tools.

I agree that there are people who don't pay attention to it. However, we shouldn't design the tutorial from the perspective that users might not be paying attention to it. That's a self defeating strategy.

If we put the table with GUI tools on top, that would be the part with most focus from users. That's not how it should be.

[Kavita-Dhole]

Hello, can you please assign me this issue