Reorganize and edit for clarity and concision #1
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
It is easier for users when all information about a concept is presented together. It is also easier for users to read and understand information when it is broken into logical subsections. Subsections with clear headings allow users to more easily skim to find the information they need. This commit moves information related to each command from the original paragraph to a new section labeled with the command name. It also moves additional context that applies to more than one of the commands to the top of the article.
Users viewing this article are likely relatively new to Git. They may be unsure of how and when to use push, pull, and fetch. This commit adds context to the top of this article that helps users understand how these commands are related and what tasks they will use them for. It removes a sentence that states that push and pull are described as equivalent to avoid introducing conjecture into the documentation.
Commands should be listed in the same order in the title, context, and subsections to make it easier for users to read and understand this answer. This commit ensures that the commands are in the same order in the title, context, and subsections. It also places the commands in a more logical order. Pull builds upon fetch, so users should read about fetch first, then pull, and then push.
Git fetch gets all changes from the remote repository, including new branches and tags, and places them in the user's local repository. This commit updates the text to explain that fetch retrieves all changes, not just the changes on the user's current branch. This commit also updates the language so that it does not use the term pull to describe the results from fetch. That could be confusing for users, as pull is a separate Git command that works differently from fetch. This commit also updates the context about how to merge changes so that the documentation does not assume the name of the user's working local branch. Finally, this commit makes the description more concise and addresses the user as 'you,' not 'we.'
Users visiting this documentation are likely new to Git commands and may not remember exactly what a git fetch and git merge do when reading this answer. This commit describes both actions involved in a git pull using a bullet format to make the text easier to read. This commit also removes the extra sentence about how some users prefer to use git fetch and git merge separately so that they can review changes, because this documentation already provides that context as part of the fetch subsection. Finally, this commit makes the text more concise and addresses the user as 'you,' rather than 'we'.
This commmit adds the equivalent commands (fetch and merge) into the corresponding bullets under the Pull section. This will help users more quickly understand what each step does and that it is equivalent to a git command without adding an extra line to the documentation.
This commit makes the text more concise and addresses the user as 'you' while removing mentions of 'our' and 'we,' as the author and the user are not actually working on this task together. This commit also tells the user how to push successfully by reminding them that they must update their local branch before pushing and telling them how to do so. The phrasing "Before you can push" helps flag for the user that this is something they must do beforehand, reducing the chance that they try to push, fail, and then have to come back to the documentation to understand why. Finally, this commit removes the sentences about how Git checks for a remote tracking branch. The previous text doesn't tell the user what a remote tracking branch is or how to set one. A better alternative is to make the text more concise by asserting that the changes will go to the remote tracking branch and provide an in-text link to documentation explaining tracking branches and how to set them. This allows this section to focus on defining the push command, while providing additional information for users who may need it.
It is easier for users to find information when section titles are task-based. That is, when titles describe actions that the user wants to do while they are working, rather than specific commands or features. This commit updates the title of this article to be task-based and updates the description so that it adds additional context instead of just repeating the title. This will help users better understand how this information is relevant to their work and when to use git fetch, pull, and push.
This commit removes the command names from the context at the top of the article. The command names were redundant, as they are listed below, and now the text is more concise.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
I have edited the description of git fetch, pull, and push so that it will be easier for users to read and understand. Note that I have made the following assumptions: