diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml deleted file mode 100644 index 3ba13e0c..00000000 --- a/.github/ISSUE_TEMPLATE/config.yml +++ /dev/null @@ -1 +0,0 @@ -blank_issues_enabled: false diff --git a/.github/ISSUE_TEMPLATE/general-issue-template.md b/.github/ISSUE_TEMPLATE/general-issue-template.md deleted file mode 100644 index f87b5043..00000000 --- a/.github/ISSUE_TEMPLATE/general-issue-template.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -name: General issue template -about: Use this template to report all feedback/issues for the Microsoft Learn contributor guide. -title: '' -labels: '' -assignees: carlyrevier, jehchow - ---- - ---- -**PLEASE READ AND THEN DELETE BEFORE SUBMITTING YOUR ISSUE** - -Welcome to the Microsoft Learn contributor guide feedback form! - -Issues submitted here are reviewed by the repo managers of the contributor guide, **not product teams.** Your issue should pertain to the documentation in this [contributor guide](https://learn.microsoft.com/contribute) only. Requests for updates to products or product documentation will be closed. - -If you have feedback about a product or product documentation, use one of these outlets instead: - -- For Microsoft Learn documentation: Either the feedback link at the top of the article, or the feedback area at the bottom of an article. If there is none, post to our [feedback portal](https://feedbackportal.microsoft.com/feedback/). - -- For Microsoft Learn training content: The **reporting an issue** feedback link at the bottom of each unit. If there is none, use the **Report feedback** tool at the very bottom of [this article](https://learn.microsoft.com/learn/support/troubleshooting?branch=main#report-feedback). - -Thank you! diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 25e00932..a7d3f0bf 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -4,7 +4,7 @@ Thanks for contributing to the [Microsoft Learn contributor guide](https://learn ## Quality control -- [ ] 1. **Successful build with no warnings**: Review the build status to make sure **all checks are green** (Succeeded). +- [ ] 1. **Successful build with no warnings or errors**: Review the build status to make sure **all checks are green** (Succeeded). - [ ] 2. **#Sign-off**: Once the PR is finalized and ready to be merged, indicate so by typing `#sign-off` in a new comment in the PR. Signing off means the document is ready for review and can be published at any time. @@ -15,5 +15,4 @@ Thanks for contributing to the [Microsoft Learn contributor guide](https://learn ## Need help? -- If you have an open PR, tag the PR reviewers in comment with your question: `@carlyrevier, @jehchow` -- Open an issue in this repo and tag the PR reviewers. +If you have an open PR, tag the PR reviewers in a comment with your question: `@carlyrevier, @jehchow` diff --git a/Contribute/content/docs-authoring/metadata-explorer.md b/Contribute/content/docs-authoring/metadata-explorer.md index bc2b6858..5fd0e3a1 100644 --- a/Contribute/content/docs-authoring/metadata-explorer.md +++ b/Contribute/content/docs-authoring/metadata-explorer.md @@ -15,7 +15,7 @@ feedback_product_url: https://github.com/microsoft/vscode-docs-authoring/issues ## Summary -The Metadata explorer appears automatically in the Explorer side bar of Visual Studio Code when you open a Learn Markdown file. It has two main sections: [required metadata](../metadata.md#required-metadata) and [optional metadata](../metadata.md#optional-metadata). +The Metadata explorer appears automatically in the Explorer sidebar of Visual Studio Code when you open a Learn Markdown file. It has two main sections: [required metadata](../metadata.md#required-metadata) and [optional metadata](../metadata.md#optional-metadata). :::image type="content" source="media/metadata-explorer.PNG" alt-text="Metadata explorer in Visual Studio Code"::: diff --git a/Contribute/content/git-github-fundamentals.md b/Contribute/content/git-github-fundamentals.md index 7d882a37..ba9e019e 100644 --- a/Contribute/content/git-github-fundamentals.md +++ b/Contribute/content/git-github-fundamentals.md @@ -1,6 +1,6 @@ --- title: Git and GitHub essentials for Microsoft Learn documentation -description: This article defines key terms, provides an overview of Git and GitHub repositories, and explains how content is organized for Microsoft technical documentation. +description: This article defines key terms, provides an overview of Git and GitHub repositories, and explains how content is organized for Microsoft Learn documentation. author: carlyrevier ms.author: cahublou ms.topic: contributor-guide @@ -99,7 +99,7 @@ This term is the name assigned to the connection between your local repository a A *pull request* (PR) is a request for a content owner to pull your changes into the official source. A PR enables GitHub's collaboration model by asking for the changes (also known as *commits*) from your working branch to be pulled and merged into another branch. In most cases, that other branch is the default branch in the main repository. -A PR also serves as a mechanism to provide the contributor with feedback from Microsoft Learn's validation processes and the PR reviewer, to resolve potential issues or questions before the changes are merged into the default branch. +A PR also serves as a mechanism to provide the contributor with feedback from Microsoft Learn's validation processes and the PR reviewer to resolve issues or questions before the changes are merged into the default branch. ## Remote diff --git a/Contribute/content/how-to-create-github-issues.md b/Contribute/content/how-to-create-github-issues.md index f98363b8..9d6dbd47 100644 --- a/Contribute/content/how-to-create-github-issues.md +++ b/Contribute/content/how-to-create-github-issues.md @@ -1,22 +1,25 @@ --- -title: Create GitHub issues for Microsoft Learn documentation -description: Learn how to create issues in GitHub when you spot errors in Microsoft Learn documentation. +title: Create GitHub issues for open-source products +description: Learn how to create issues in GitHub to alert the content team when you spot errors in Microsoft Learn documentation for open-source products. author: carlyrevier ms.author: cahublou -ms.date: 08/28/2023 +ms.date: 02/23/2024 ms.topic: contributor-guide ms.prod: non-product-specific ms.custom: external-contributor-guide --- -# Create GitHub issues +# Create GitHub issues for open-source products -This article teaches you how to create a GitHub issue for Microsoft Learn documentation. It also teaches you how to peruse other users' issues and either add your own comments to them or open a pull request (PR) to address them. +This article teaches you how to create a GitHub issue for Microsoft Learn documentation related to open-source products. It also teaches you how to peruse other users' issues and either add your own comments to them or open a pull request (PR) to address them. -Our documentation is a continuous work in progress. Receiving good GitHub issues from contributors helps us focus our efforts on the highest priorities for the community. +Our open-source product documentation is a continuous work in progress. Receiving good GitHub issues from contributors helps us focus our efforts on the highest priorities for the community. Of course, if you know how to fix an issue, we invite you to [make the changes yourself](how-to-write-quick-edits.md), instead of opening an issue. +> [!NOTE] +> Only open-source products using the open-source feedback experience accept GitHub issues. For more information and a list of participating repositories, see [Use the open-source experience](provide-feedback.md#use-the-open-source-experience). To leave feedback on non-open-source product documentation, see [Provide feedback on Microsoft Learn](provide-feedback.md). + ## Prerequisites - [Create a GitHub account](index.md#create-a-github-account), if you don't have one. @@ -24,29 +27,27 @@ Of course, if you know how to fix an issue, we invite you to [make the changes y ## Create an issue 1. Navigate to the article you want to comment on. -1. Scroll to the bottom of the article, where you'll see options for submitting feedback on either the topic itself or the product. Select the **This page** link to submit feedback on the topic. +1. Scroll to the bottom of the article, where you'll see options for submitting feedback. Select **Open a documentation issue** to create a new issue. This feedback is specific to the content and is tracked as an issue in GitHub. ![Screenshot of the bottom of an article, showing the feedback options.](media/how-to-create-github-issues/feedback-links.png) - - Selecting **This product** takes you to a destination (for example, UserVoice, GitHub, an email address) where you can provide feedback on the product itself. This feedback is independent of the content and has no relationship back to the original article. - - Selecting **This page** opens a new issue for you in the GitHub repository that stores the content for the article you're viewing. This feedback is specific to the content and is tracked as an issue in GitHub. - - Selecting **View all page feedback** allows you to see all feedback submitted for the article. Anyone can read the feedback, but you must be signed in to comment or leave feedback. + Optionally, select **Provide product feedback** to go to a destination (for example, a feedback portal, GitHub, an email address) where you can provide feedback on the product itself. This feedback is independent of the content and has no relationship back to the original article. -1. The system opens a new issue for you in the GitHub repository that stores the content for the article you're viewing. Replace the **[Enter feedback here]** placeholder with your feedback, add a title, and select **Submit new issue**. Don't change any content in the **Document Details** section. +1. The system opens a new issue for you in the GitHub repository that stores the content for the article you're viewing. Add a title and a description; all other fields should populate for you automatically. When you're done, select **Submit new issue**. - :::image type="content" source="media/how-to-create-github-issues/github-issue.png" alt-text="Screenshot of a new issue in GitHub."::: + :::image type="content" source="media/how-to-create-github-issues/github-issue.png" alt-text="Screenshot of the new-issue form in GitHub."::: - The more detail you can provide, the more helpful the issue. Tell us what information you sought. Tell us the search terms you used. If you can't get started, tell us how you want to start exploring unfamiliar technology. + The more detail you provide, the more helpful the issue is. Tell us what information you sought or the search terms you used to get to this article. If you can't get started, tell us how you want to start exploring unfamiliar technology. You can also add screenshots or files to help us understand your issue. -That's it! Your issue is now added to the Issues queue. Issues start the conversation about what's needed. The content team will respond to these issues with ideas for what we can add and ask for your opinions. When we create a draft, we'll ask you to [review the PR](#review-open-prs). +That's it! Your issue is now added to the Issues queue. Issues start the conversation about what's needed. The content team will respond to these issues with ideas for what we can add and ask for your opinions. When we create a draft, we'll ask you to [review the PR](how-to-review-pull-request.md). ## Comment on an issue -You can comment on any issue in the repository. You can also add your own comments to an issue you've created. +You can comment on any issue in a repository that supports GitHub issues. You can also add your own comments to an issue you've created. -1. Find the issue you want to comment on. In your browser, navigate to the GitHub repository you want to look at issues for. Choose the **Issues** tab to see the open issues for that repo. If the repo has a lot of issues, use the **Filters** bar to filter by label, author, and more. Or use the **Search** bar to look for specific queries. +1. Find the issue you want to comment on. In your browser, navigate to the GitHub repository you want to look at issues for. Choose the **Issues** tab to see the open issues for that repo. If the repo has a lot of issues, use the **Filters** bar to filter by label, author, and more. Or use the **Search** bar to look for specific queries. Once you find an issue that appeals to you, select it to open it. - If you're not sure which repo to look at, find one that interests you in our [list of Microsoft Learn repos](https://github.com/orgs/MicrosoftDocs/repositories). + Only open-source products using the open-source feedback experience accept GitHub issues. For more information and a list of participating repositories, see [Use the open-source experience](provide-feedback.md#use-the-open-source-experience). 1. Read the issue and any comments that have already been added by others. If you want to add a comment, scroll to the bottom of the issue and enter your comment in the **Leave a comment** box. When you're done, select **Comment**. diff --git a/Contribute/content/how-to-write-quick-edits.md b/Contribute/content/how-to-write-quick-edits.md index 97f4b395..37cce47a 100644 --- a/Contribute/content/how-to-write-quick-edits.md +++ b/Contribute/content/how-to-write-quick-edits.md @@ -1,6 +1,6 @@ --- title: Edit Microsoft Learn documentation in the browser -description: Learn how to edit a Microsoft Learn documentation article in the browser using GitHub. +description: Learn how to edit a Microsoft Learn article in the browser using GitHub's user interface and without having to download or install tools. author: carlyrevier ms.author: cahublou ms.date: 02/01/2024 @@ -16,7 +16,7 @@ ms.custom: external-contributor-guide Several of Microsoft's documentation sets are open source and hosted on GitHub. While not all documentation sets are completely open source, many have public-facing repositories where you can suggest changes via pull requests (PRs). This open-source approach streamlines and improves communication between product engineers, content teams, and customers. -Quick edits facilitate the process to report and fix small errors and omissions in documentation. Despite all efforts, small grammar and spelling errors _do_ make their way into our published documents. While you can create issues to report mistakes, it's faster and easier to create a PR to fix the issue when the option is available. +Quick edits facilitate the process to report and fix small errors and omissions in documentation. Despite all efforts, small grammar and spelling errors _do_ make their way into our published documents. We appreciate your help in identifying and fixing these issues! We use PRs for all changes, even for contributors who have write access. Most repositories protect the default branch, so updates must be submitted as PRs. @@ -62,5 +62,5 @@ We use PRs for all changes, even for contributors who have write access. Most re ## Limitations -- Most localized (i.e., translated) documentation doesn't offer the ability to edit or provide feedback through GitHub. To provide feedback on localized content, use the [Provide Feedback](https://aka.ms/provide-feedback) form. +- Most localized (i.e., translated) content doesn't offer the ability to edit through GitHub. However, you can provide feedback on translation quality by selecting the Feedback (thumbs) button at the top of the page and then choosing the **Translation quality** reason. You can also leave more specific feedback on localized content by using the [Provide Feedback](https://aka.ms/provide-feedback) form. - The in-browser editing experience works best for minor and infrequent changes. If you make large contributions or use advanced Git features (such as branch management or advanced merge conflict resolution), we recommend that you [fork the repo and work locally](how-to-write-workflows-major.md). diff --git a/Contribute/content/index.md b/Contribute/content/index.md index c6eb9520..63aaeceb 100644 --- a/Contribute/content/index.md +++ b/Contribute/content/index.md @@ -35,7 +35,7 @@ Once you've set up your accounts, select a contribution option from the table to |[Edit documentation](how-to-write-overview.md) | GitHub | |[Review pull requests](how-to-review-pull-request.md) | GitHub | |[Provide feedback on content](provide-feedback.md) | None for standard experience; GitHub for open-source experience | -|[Create GitHub issues](how-to-create-github-issues.md) | GitHub | +|[Create GitHub issues for open-source product documentation](how-to-create-github-issues.md) | GitHub | |[Answer questions on Microsoft Q&A](qna-overview.md) | Microsoft | |[Create a Collection](collections.md) | Microsoft | |[Participate in the Microsoft Learn Tech Community](https://techcommunity.microsoft.com/t5/microsoft-learn/ct-p/MicrosoftLearn) | Microsoft | diff --git a/Contribute/content/media/how-to-create-github-issues/feedback-links.png b/Contribute/content/media/how-to-create-github-issues/feedback-links.png index 85cd8d5a..2ecb6ce1 100644 Binary files a/Contribute/content/media/how-to-create-github-issues/feedback-links.png and b/Contribute/content/media/how-to-create-github-issues/feedback-links.png differ diff --git a/Contribute/content/media/how-to-create-github-issues/github-issue.png b/Contribute/content/media/how-to-create-github-issues/github-issue.png index d5e7995f..fe1942e3 100644 Binary files a/Contribute/content/media/how-to-create-github-issues/github-issue.png and b/Contribute/content/media/how-to-create-github-issues/github-issue.png differ diff --git a/Contribute/content/provide-feedback.md b/Contribute/content/provide-feedback.md index 84e435eb..1a3b4d8d 100644 --- a/Contribute/content/provide-feedback.md +++ b/Contribute/content/provide-feedback.md @@ -87,6 +87,7 @@ Currently, the open-source experience is enabled for the following repositories: - MicrosoftDocs/azure-docs-powershell - MicrosoftDocs/azure-docs-sdk-node - MicrosoftDocs/azure-docs-sdk-python +- MicrosoftDocs/community-content - MicrosoftDocs/microsoft-365-community - MicrosoftDocs/PowerShell-Docs - MicrosoftDocs/PowerShell-Docs-DSC diff --git a/Contribute/index.yml b/Contribute/index.yml index 5299f0df..9f31a060 100644 --- a/Contribute/index.yml +++ b/Contribute/index.yml @@ -135,9 +135,9 @@ sections: title: Frequently asked questions questions: - question: How do I become a Microsoft Learn contributor? - answer: There's more than one way to become a contributor! While editing documentation is the most popular method, you can also answer questions in Microsoft Q&A, create a collection of content for others to consume, or file a GitHub issue if you spot problems in our content but don't have the tools to fix them yourself. + answer: There's more than one way to become a contributor! While editing documentation is the most popular method, you can also answer questions in Microsoft Q&A, leave feedback on documentation and training content, create a collection of content for others to consume, or file a GitHub issue if you spot problems in open-source product documentation but don't have the tools to fix them yourself. - question: What accounts do contributors need? - answer: We recommend having a Microsoft Learn account and a GitHub account. A Microsoft Learn account allows you to contribute to Q&A and create collections, while a GitHub account allows you to edit our open-source documentation or file an issue about documentation. + answer: We recommend having a Microsoft Learn account and a GitHub account. A Microsoft Learn account allows you to contribute to Q&A and create collections, while a GitHub account allows you to edit our documentation or file an issue about open-source product documentation. - question: How do I start contributing to Microsoft Learn documentation? answer: Check out our contributor guide! Start with the article on [how to get started](https://learn.microsoft.com/contribute/content/?branch=main#how-do-i-start). You'll find a table that guides you to documentation for each contribution type and lists the account you'll need for each option. The contributor guide is your home base for learning how to get up and running as a Microsoft Learn contributor! - question: Who contributes to Microsoft Learn?