Added Documentation #935
Added Documentation #935
Conversation
|
It looks like the documentation here is out of date: It suggests assessing the GitHub Extension by selecting 'View > Other Windows > GitHub' from the main menu (which is currently just the PR list). It should maybe mention something about the icons and repo list on the 'Team Explorer' pane. I hear @beardofedu might have something to do with these pages? 😄 |
|
Just listing out the additional things to add to the docs, feel free to add more if I missed anything:
|
bernars
left a comment
bernars
left a comment
There was a problem hiding this comment.
I'm super impressed with how this has shaped up! I've dropped some comments to tighten up the content with small changes that make the content a little easier to parse, please let me know if you have ANY questions!
|
|
||
| After you provide your GitHub or GitHub Enterprise credentials to GitHub for Visual Studio, the extension automatically detects the personal and organization repositories you have access to on your account. | ||
|
|
||
| 1. Open **Team Explorer**. TODO: screenshot |
There was a problem hiding this comment.
Where do you click, approximately? Things like "In the top-right corner of the page..." or "Under the ______..." help a lot to orient the user.
|
|
||
| 1. Open **Team Explorer**. TODO: screenshot | ||
| 2. Click the **Manage Connections** toolbar button. TODO: screenshot | ||
| 3. Click the **Clone** link next to the account you want to clone the repository from. TODO: screenshot |
There was a problem hiding this comment.
Click the Clone link next to the account you want to clone the repository from.
It's best to orient the user, then tell them what to do when they get there (this makes it so they can read the instruction once, memorize it handily, and complete the action based on their memory), like so:
Next to the account you want to clone from, click Clone.
| 1. Open **Team Explorer**. TODO: screenshot | ||
| 2. Click the **Manage Connections** toolbar button. TODO: screenshot | ||
| 3. Click the **Clone** link next to the account you want to clone the repository from. TODO: screenshot | ||
| 4. In the list of repositories, click the repository you'd like to clone. TODO: screenshot |
| 2. Click the **Manage Connections** toolbar button. TODO: screenshot | ||
| 3. Click the **Clone** link next to the account you want to clone the repository from. TODO: screenshot | ||
| 4. In the list of repositories, click the repository you'd like to clone. TODO: screenshot | ||
| 5. Change the local path for the clone if necessary. TODO: screenshot |
There was a problem hiding this comment.
Change the local path for the clone if necessary.
I like to let them explicitly know that they're 👌 leaving the default when that's true, something like:
If desired, change the local path where you'd like your clone established, or leave the default path as-is.
| 3. Click the **Clone** link next to the account you want to clone the repository from. TODO: screenshot | ||
| 4. In the list of repositories, click the repository you'd like to clone. TODO: screenshot | ||
| 5. Change the local path for the clone if necessary. TODO: screenshot | ||
| 6. Click the **Clone** button. |
There was a problem hiding this comment.
Is this button right next to where the action happens in the previous step? If so, consider combining the two:
If desired, change the local path where you'd like your clone established, or leave the default. Click Clone.
|
|
||
| > Note: for this to work with Pull Requests that come from forks, then you must be a maintainer on the repository and the Pull Request submitter must have checked [Allow edits from maintainers](https://help.github.com/articles/allowing-changes-to-a-pull-request-branch-created-from-a-fork/) when submitting the Pull Request. | ||
|
|
||
| If there are remote changes to the pull request branch then they must be pulled before you can push your changes. No newline at end of file |
There was a problem hiding this comment.
If there are remote changes to the pull request branch then they must be pulled before you can push your changes.
What about:
"If there are commits on the branch on the remote repository that you don't have on your local clone, you must pull them to your local clone and resolve any conflicts before you can push your local commits back to the remote repository."
We have some articles for resolving merge conflicts (a daunting task to some) that you might consider linking to: https://help.github.com/articles/addressing-merge-conflicts/.
| 1. Open a solution in Visual Studio. | ||
| 2. If solution is not already initialized as a git repository, select **Add to Source Control** from the **File** menu. TODO: screenshot | ||
| 3. Open **Team Explorer**. TODO: screenshot | ||
| 4. Click the **Sync** button in Team Explorer. TODO: screenshot |
There was a problem hiding this comment.
Click the Sync button in Team Explorer.
How about:
"In Team Explorer, click Sync."
| 2. If solution is not already initialized as a git repository, select **Add to Source Control** from the **File** menu. TODO: screenshot | ||
| 3. Open **Team Explorer**. TODO: screenshot | ||
| 4. Click the **Sync** button in Team Explorer. TODO: screenshot | ||
| 5. Click the **Publish to GitHub** button. TODO: screenshot |
There was a problem hiding this comment.
Click the Publish to GitHub button.
We don't explicitly call out "button" or "link" or "menu", we just refer to the label in bold: https://manual-of-style.githubapp.com/typography/#ui-elements
| 3. Click the **Connect** link in the GitHub section. If you are already connected to a GitHub instance and want to connect to another, this link will not be visible; instead click **Manage Connections** and then **Connect to GitHub**. | ||
|  | ||
| 4. In the **Connect to GitHub dialog** choose **GitHub** or **GitHub Enterprise**, depending on which product you're using. | ||
| 5. Type your credentials, then click the **Login** button. No newline at end of file |
There was a problem hiding this comment.
click the Login button.
This looks like it's referring to the action of signing in; can you change that UI text to match our terminology guidelines? https://manual-of-style.githubapp.com/terminology/#general-terminology
|
|
||
| ## Installing from the Visual Studio gallery | ||
|
|
||
| If you're currently running Visual Studio 2015 or higher, you can install the extension from the Visual Studio gallery with the following steps: |
There was a problem hiding this comment.
If you're currently running Visual Studio 2015 or higher, you can install the extension from the Visual Studio gallery with the following steps:
You can omit "... with the following steps" here:
If you're currently running Visual Studio 2015 or higher, you can install the extension from the Visual Studio gallery.
|
Thanks so much for the review @bernars! I've incorporated most of the fixes suggested. Some of them require fixes in multiple pages, but the main takeaways are to: Use "Sign in" instead of "Log in"Orient the user, then tell them what to do when they get thereFor example,
Instead of
Be aware of where to capitalize
You can omit button/link/menu vocabulary
I wasn't sure how to rework the suggestion here so I left it for now. |
|
Those are the main takeaways, @paladique! These are looking SO GOOD. |
|
Should we include a FAQ page, like we do on the site? |
|
In general, I'm against FAQs. 18f describes why so beautifully that I always leave that to them. With that said, we did create a VERY SMALL HANDFUL of FAQs for the GItHub Desktop site, and they were truly questions that Web Support was getting over and over again. You'll notice they follow a common pattern:
Hope that's helpful! |
|
This is looking SO GOOD! 🎉 ❤️ |
|
@bernars @shana @paladique @jcansdale I think we're just about ready for v1.0 of docs. I've removed the WIP label, time for a final review! |
|
LGTM! One thing we should do is add descriptions to all |
|
|
|
CONGRATULATIONS! 👏 📚 💥 |
Uh oh!
There was an error while loading. Please reload this page.