diff --git a/Contribute/content/architecture-center/aac-contribute.md b/Contribute/content/architecture-center/aac-contribute.md index 2b3dcee0..2140047f 100644 --- a/Contribute/content/architecture-center/aac-contribute.md +++ b/Contribute/content/architecture-center/aac-contribute.md @@ -6,26 +6,26 @@ ms.prod: non-product-specific ms.custom: external-contributor-guide author: martinekuan ms.author: martinek -ms.date: 09/15/2023 +ms.date: 02/01/2024 --- # Patterns and Practices contributions -Patterns and Practices content helps customers design, build, and operate solutions on Azure, and is composed from three different content portfolios. Contributions are encouraged through GitHub pull requests and issues. +Patterns and Practices content helps customers design, build, and operate solutions on Azure. The content comprises three content portfolios listed below. Contributions are encouraged through GitHub pull requests and issues. -| Portfolio | Summary | Repository | +| Portfolio | Summary | Repository | |-----------|---------|------------| -| Azure Architecture Center | Guidance for architecting solutions on Azure using established patterns and practices, incorporating the five pillars of architectural excellence. Use the technology choices and guides to determine the services that are right for your solution or industry. | https://github.com/microsoftdocs/architecture-center | -| Azure Well-Architected Framework | A set of guiding tenets to improve the quality of a workload. The framework consists of five pillars of architectural excellence, to help produce a high quality, stable, and efficient cloud architecture: reliability, security, cost optimization, operational excellence, and performance efficiency. | https://github.com/microsoftdocs/well-architected | -| Cloud Adoption Framework for Azure | A full lifecycle framework that enables cloud architects, IT professionals, and business decision makers to achieve their cloud adoption goals. Best practices, documentation, and tools help you create and implement business and technology strategies for the cloud. | https://github.com/microsoftdocs/cloud-adoption-framework | +| Azure Architecture Center | Guidance for architecting solutions on Azure using established patterns and practices, incorporating the five pillars of architectural excellence. Use the technology choices and guides to determine the services that are right for your solution or industry. | [https://github.com/microsoftdocs/architecture-center](https://github.com/microsoftdocs/architecture-center) | +| Azure Well-Architected Framework | A set of guiding tenets to improve the quality of a workload. The framework consists of five pillars of architectural excellence to help produce a high-quality, stable, and efficient cloud architecture: reliability, security, cost optimization, operational excellence, and performance efficiency. | [https://github.com/microsoftdocs/well-architected](https://github.com/microsoftdocs/well-architected) | +| Cloud Adoption Framework for Azure | A full lifecycle framework that enables cloud architects, IT professionals, and business decision-makers to achieve their cloud-adoption goals. Best practices, documentation, and tools help you create and implement business and technology strategies for the cloud. | [https://github.com/microsoftdocs/cloud-adoption-framework](https://github.com/microsoftdocs/cloud-adoption-framework) | -## Propose changes to an existing article +## Propose changes to an article -You can propose small changes to an existing content if you see a typo or want to make a correction, add a link, or add more details. Please ensure that your contribution is technically accurate, and provides helpful or valuable information in the context of the article. To get started, click the "Edit this document" pencil icon in the upper right corner of the page you'd like to contribute to. See [the contributor guide overview](../index.md#quick-edits-to-documentation) for complete details and more. +You can propose small changes to content if you want to correct a typo or error, add a link, or add more details. Ensure that your contribution is technically accurate and provides helpful or valuable information in the context of the article. To get started, select the "Edit this document" pencil icon in the upper-right corner of the page you'd like to contribute to. See [Edit Microsoft Learn documentation](../how-to-write-quick-edits.md) for more details. ## Submit a content suggestion -If you would like to propose new content or substantial changes to existing content, use the links below to file a GitHub issue in the appropriate repository: +If you'd like to propose new content or substantial changes to content, use the links below to file a GitHub issue in the appropriate repository: [Azure Architecture Center proposal](https://github.com/MicrosoftDocs/architecture-center/issues/new?title=Content%20suggestion&body=Provide%20a%20detailed%20description%20of%20your%20proposal,%20including%20links%20to%20related%20or%20impacted%20articles,%20and%20any%20relevant%20attachments:) diff --git a/Contribute/content/dotnet/dotnet-contribute.md b/Contribute/content/dotnet/dotnet-contribute.md index e9138b7b..6b239970 100644 --- a/Contribute/content/dotnet/dotnet-contribute.md +++ b/Contribute/content/dotnet/dotnet-contribute.md @@ -6,7 +6,7 @@ ms.prod: non-product-specific ms.custom: external-contributor-guide ms.date: 04/08/2021 --- -# Learn how to contribute to the .NET documentation repositories +# Contribute to the .NET documentation repositories Thank you for your interest in contributing to the .NET documentation! @@ -22,7 +22,7 @@ The .NET documentation site is built from multiple repositories. These are just ## Guidelines for contributions -We appreciate community contributions to docs. The following list shows some guiding rules to keep in mind when you're contributing to the .NET documentation: +We appreciate community contributions to documentation. The following list shows some guiding rules to keep in mind when you're contributing to .NET documentation: - **DON'T** surprise us with large pull requests. Instead, file an issue and start a discussion so we can agree on a direction before you invest a large amount of time. - **DON'T** include sample code inline in an article. @@ -35,9 +35,9 @@ We appreciate community contributions to docs. The following list shows some gui Following these guidelines will ensure a better experience for you and for us. -## Make a contribution to .NET docs +## Contribution process -**Step 1:** If you're interested in writing new content or in thoroughly revising existing content, open an [issue](https://github.com/dotnet/docs/issues) describing what you want to do. The content inside the **docs** folder is organized into sections that are reflected in the Table of Contents (TOC). Define where the topic will be located in the TOC. Get feedback on your proposal. +**Step 1:** If you're interested in writing new content or in thoroughly revising existing content, open an [issue](https://github.com/dotnet/docs/issues) describing what you want to do. The content inside the **docs** folder is organized into sections that are reflected in the table of contents (TOC). Define where the topic will be located in the TOC. Get feedback on your proposal. -or- @@ -49,17 +49,17 @@ Choose an existing issue and address it. You can look at our [open issues](https When you find an issue to work on, add a comment to ask if it's open. -Once you've picked a task to work on, follow the [get started](../get-started-setup-github.md) guide to create a GitHub account and set up your environment. +Once you've picked a task to work on, [create a GitHub account](../index.md#create-a-github-account) and move on to Step 2. **Step 2:** Fork the `/dotnet/docs` repo (or whichever repo you're contributing to) as needed and create a branch for your changes. -For small changes, see [Quick edits to documentation](../index.md#quick-edits-to-documentation). +For small changes, see [Edit in the browser](../how-to-write-quick-edits.md). **Step 3:** Make the changes on this new branch. If it's a new topic, you can use this [template file](dotnet-style-guide.md) as your starting point. It contains the writing guidelines and also explains the metadata required for each article, such as author information. For more information on the Markdown syntax used in Microsoft Learn content, see [Markdown reference](../markdown-reference.md). -Navigate to the folder that corresponds to the TOC location determined for your article in step 1. That folder contains the Markdown files for all articles in that section. If necessary, create a new folder to place the files for your content. The main article for that section is called *index.md*. +Navigate to the folder that corresponds to the TOC location determined for your article in Step 1. That folder contains the Markdown files for all articles in that section. If necessary, create a new folder to place the files for your content. The main article for that section is called *index.md*. For images and other static resources, create a subfolder called **media** inside the folder that contains your article, if it doesn't already exist. Inside the **media** folder, create a subfolder with the article name (except for the index file). For more information about where to place your files, see the [Example folder structure](#example-folder-structure) section. diff --git a/Contribute/content/how-to-write-overview.md b/Contribute/content/how-to-write-overview.md index e2e268b8..1da3c1b5 100644 --- a/Contribute/content/how-to-write-overview.md +++ b/Contribute/content/how-to-write-overview.md @@ -3,7 +3,7 @@ title: Overview of editing documentation on Microsoft Learn description: Learn how to get started editing documentation on Microsoft Learn, and learn how to choose the appropriate method for contribution. author: carlyrevier ms.author: cahublou -ms.date: 08/31/2023 +ms.date: 02/01/2024 ms.topic: contributor-guide ms.prod: non-product-specific ms.custom: external-contributor-guide @@ -13,18 +13,48 @@ ms.custom: external-contributor-guide Thank you for your interest in editing documentation on Microsoft Learn! Your contributions help us ensure our documentation is well written, up to date, and accurate. The information on this page will help you decide which method of contribution is best for you. -Before you get started, make sure you're signed in to your GitHub account. If you don't have one, navigate to [https://github.com/join](https://github.com/join) for a fast and free sign-up process. +## Prerequisite + +Before you get started, make sure you're signed in to your GitHub account. If you don't have a GitHub account, navigate to [https://github.com/join](https://github.com/join) for a fast and free sign-up process. + +## Minor changes to documentation + +Minor changes are quick and easy. Examples of minor changes include: + +- Fixing typos +- Revising a single article +- Adding a section to an article +- Correcting an error +- Updating broken links + +If you're making minor changes, all you need is a GitHub account! + +To make a minor change, select the **Edit This Document** pencil icon at the top of the article. This action takes you to the source file on GitHub, where you can make your changes. When you're finished, you'll be prompted to create a pull request (PR) to propose your changes. For a full walkthrough of this process, see [Edit documentation in the browser](how-to-write-quick-edits.md). + +## Major changes to documentation + +Major changes involve more time and effort. Examples of major changes include: + +- Complex changes that will take you several days to complete +- Revisions to multiple articles that you want to submit together +- Creating a new article +- Contributing often + +If you're making major changes, you need to download and install a few tools to make your work easier. Follow these steps to get started: + +1. [Install Git and Markdown tools.](get-started-setup-tools.md) +1. [Set up a local Git repository.](get-started-setup-local.md) +1. [Make changes to the documentation.](how-to-write-major-edits.md) +1. [Create a PR.](create-pull-request.md) ## Process overview -The process flow below shows the basic steps involved in getting started. Notice that some items are one-time steps, while others occur every time you start a new contribution. +The process flow below shows the high-level steps involved in getting started for minor and major changes. Notice that some items are one-time steps, while others occur every time you start a new contribution. :::image type="complex" source="media/how-to-write-overview/process-diagram.png" alt-text="Process flow map showing the basic workflow for getting started with the contribution process."::: The image starts with a decision point of Is this your first time contributing? If yes, the next step is to set up your GitHub account. If no, the next step is another decision point of Is your change minor? If yes, the next step is to edit within the browser. If no, the next steps involve installing authoring tools, forking and cloning the repo, making changes, opening a pull request, and reviewing and signing off on your pull request. :::image-end::: -## How large is your change? - -If you're making minor changes to an article, follow the steps in [Edit documentation in the browser](how-to-write-quick-edits.md). All you need is a GitHub account; you don't need to download and install any tools. Examples of minor changes are fixing typos, basic revisions to one or more articles, adding a section to an article, or updating links. +## Changes to training modules -If you're making more substantial or frequent changes, we recommend [installing Git and Markdown tools](get-started-setup-tools.md) and [forking and cloning the repo](get-started-setup-local.md). Frequent contributors typically have ongoing (long-running) changes that go through multiple build-validation-staging cycles or span multiple days before they sign off on their pull request. +Contributors can't edit or propose changes to training modules. At this time, only Microsoft Learn documentation stored in public repositories is open for public contributions. \ No newline at end of file diff --git a/Contribute/content/how-to-write-quick-edits.md b/Contribute/content/how-to-write-quick-edits.md index 09e09e89..97f4b395 100644 --- a/Contribute/content/how-to-write-quick-edits.md +++ b/Contribute/content/how-to-write-quick-edits.md @@ -3,7 +3,7 @@ title: Edit Microsoft Learn documentation in the browser description: Learn how to edit a Microsoft Learn documentation article in the browser using GitHub. author: carlyrevier ms.author: cahublou -ms.date: 08/28/2023 +ms.date: 02/01/2024 ms.topic: contributor-guide ms.prod: non-product-specific ms.custom: external-contributor-guide @@ -20,7 +20,7 @@ Quick edits facilitate the process to report and fix small errors and omissions 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. -## Prerequisites +## Prerequisite - [Create a GitHub account](index.md#create-a-github-account), if you don't have one. @@ -56,11 +56,7 @@ We use PRs for all changes, even for contributors who have write access. Most re Review your changes, and then select **Create pull request**. -1. On the **Open a pull request** page, preview your PR. You can change the title or description fields if needed. When you're ready, select **Create pull request**. This action opens your PR. - -1. If everything looks good and you're done editing, add a comment that reads `#sign-off`. This alerts the PR review team that your PR is ready to be reviewed. - - :::image type="content" source="media/how-to-write-quick-edits/sign-off.png" alt-text="Screenshot of the GitHub comment box within a PR with a comment reading #sign-off."::: +1. On the **Open a pull request** page, preview your PR. You can change the title or description fields if needed. When you're ready, select **Create pull request**. This action opens your PR and alerts the article owner that you've proposed a change. 1. That's it! Content team members will review your PR and merge it when it's approved. You may get feedback requesting changes. For more details on processing your PR, see [Process a pull request](process-pull-request.md). diff --git a/Contribute/content/media/how-to-write-quick-edits/sign-off.png b/Contribute/content/media/how-to-write-quick-edits/sign-off.png deleted file mode 100644 index 254b490e..00000000 Binary files a/Contribute/content/media/how-to-write-quick-edits/sign-off.png and /dev/null differ