Merge pull request #108866 from arpitjain099/master

Improve azure documentation

Author: Court72

markdown templates/aml-templates/template-howto.md

@@ -10,7 +10,7 @@ ms.author: your-msft-alias
 author: your-github-account-name
 ms.date: 04/10/2018
 ---
-# This H1 is the title of the article. It appears in search, appears at the top of the article, and has the second greatest impact on search. 100 chars or less.
+# This H1 is the title of the article. It appears in search, appears at the top of the article, and has the second most significant impact on search —100 chars or less.
 
 Guidance [here](https://review.learn.microsoft.com/help/contribute/contribute-how-to-write-seo-basics?branch=main)
 

markdown templates/aml-templates/template-quickstart.md

@@ -12,7 +12,7 @@ ms.date: 04/10/2018
 ---
 
 # The H1 heading is the article title that shows on the web
-Once sentence into intro about Machine Learning. Intro paragraph to explain the intent of this Quickstart, and time it takes. You can finish this Quickstart in about five minutes.
+One sentence into the intro about Machine Learning. Intro paragraph to explain the intent of this Quickstart and the time it takes. You can finish this Quickstart in about five minutes.
 
 If you don't have an Azure subscription, create a [free](https://azure.microsoft.com/free/) account before you begin.
 
@@ -31,10 +31,10 @@ Setting|Suggested value|Description
 Server name |*example-name*|Choose a unique name that identifies your Azure Machine Learning server.
 Subscription|*Your subscription*|The Azure subscription that you want to use for your server. If you have multiple subscriptions, choose the appropriate subscription in which the resource is billed for.
 Resource Group|*myresourcegroup*| You may make a new resource group name, or use an existing one from your subscription.
-Server admin login |*mylogin*| Make your own login account to use when connecting to the server. 
+Server admin login |*mylogin*| Make your login account when connecting to the server. 
 
   > [!IMPORTANT]
-  > The server admin login and password that you specify here are required to log in to the server and its databases later in this Quickstart. Remember or record this information for later use.
+  > The server admin login and password you specify here must log in to the server and its databases later in this Quickstart. Remember or record this information for later use.
 
 ## Example command using a bash shell comment
 
@@ -43,7 +43,7 @@ A code block you could use.
 tool --switch1 value2 --switch2 value2
 ```
 
-The table describes the switched used in the preceding command: 
+The table describes the switch used in the preceding command: 
 
 tool parameter |Suggested value|Description
 ---|---|---
@@ -60,17 +60,17 @@ Something happened.
 
 
 ## Clean up resources
-Clean up the resources you created in the quickstart either by deleting the [Azure resource group](../../azure-resource-manager/resource-group-overview.md), which includes all the resources in the resource group, or by deleting the one server resource if you want to keep the other resources intact.
+Clean up the resources you created in the Quickstart either by deleting the [Azure resource group](../../azure-resource-manager/resource-group-overview.md), which includes all the resources in the resource group, or by deleting the one server resource if you want to keep the other resources intact.
 
 > [!TIP]
-> Other Quickstarts in this collection build upon this quick start. If you plan to continue on to work with subsequent quickstarts, do not clean up the resources created in this quickstart. If you do not plan to continue, use the following steps to delete resources created by this quickstart in the Azure portal.
+> Other Quickstarts in this collection build upon this quick start. If you plan to continue to work with subsequent quickstarts, do not clean up the resources created in this Quickstart. If you do not plan to continue, use the following steps to delete resources created by this Quickstart in the Azure portal.
 
-To delete the entire resource group including the newly created server:
+To delete the entire resource group, including the newly created server:
 1.	Locate your resource group in the Azure portal. From the left-hand menu in the Azure portal, click **Resource groups** and then click the name of your resource group, such as our example **myresourcegroup**.
-2.	On your resource group page, click **Delete**. Then type the name of your resource group, such as our example **myresourcegroup**, in the text box to confirm deletion, and then click **Delete**.
+2.	On your resource group page, click **Delete**. Then type the name of your resource group, such as our example **myresourcegroup**, in the text box to confirm the deletion, and then click **Delete**.
 
-Or instead, to delete the newly created server:
-1.	Locate your server in the Azure portal, if you do not have it open. From the left-hand menu in Azure portal, click **All resources**, and then search for the server you created.
+Or, instead, delete the newly created server:
+1.	Locate your server in the Azure portal if you do not have it open. From the left-hand menu in Azure portal, click **All resources**, and then search for the server you created.
 2.	On the **Overview** page, click the **Delete** button on the top pane.
 3.	Confirm the server name you want to delete.
 

markdown templates/aml-templates/template-tutorial.md

@@ -11,15 +11,15 @@ author: your-github-account-name
 ms.date: 04/10/2018
 ---
 
-# Tutorial: Verb ... --> This H1 is the title of the article. It appears in search, appears at the top of article, second greatest impact on search, 100 chars or less
+# Tutorial: Verb ... --> This H1 is the title of the article. It appears in search, appears at the top of the article, and has the second greatest impact on search, 100 chars or less
 
-AUTHORS: A single sentence intro about AML. Intro paragraph to explain the intent of this tutorial. Lead with a light intro that describes, in customer-friendly language, what they’ll learn, or do, or accomplish. Answer the fundamental “why would I want to do this?” question. Avoid starting the tutorial with a bunch of notes or caveats.
+AUTHORS: A single-sentence intro about AML. Intro paragraph to explain the intent of this tutorial. Lead with a light introduction that describes, in customer-friendly language, what they'll learn, or do, or accomplish. Answer the fundamental "why would I want to do this?" question. Avoid starting the tutorial with a bunch of notes or caveats.
 
-In this tutorial you will do X...
+In this tutorial, you will do X...
 
 AUTHORS: Quick read tutorial [here](https://review.learn.microsoft.com/help/contribute/contribute-how-to-mvc-tutorial?branch=main). Also, don't forget to run Acrolinx to find issues before you commit.
 
-In this tutorial, you use X to do Y or you learn how to:
+In this tutorial, you use X to do Y, or you learn how to:
 > [!div class="checklist"]
 > * Create something
 > * Do something
@@ -29,9 +29,9 @@ In this tutorial, you use X to do Y or you learn how to:
 > [Important!]
 > Avoid notes, tips, and important boxes. Except for this one, ha!
 > 
-> Tutorials are typically longer and more complex than quickstarts. They are created from the list of top user tasks identified in milestone one and focus on the single best procedure for completing that task. A tutorial usually aligns to one or two customer tasks. At a minimum, you need one tutorial in the Tutorials node of the TOC.
+> Tutorials are typically longer and more complex than quickstarts. They are created from the list of top user tasks identified in milestone one and focus on the best procedure for completing that task. A tutorial usually aligns with one or two customer tasks. At a minimum, you need one tutorial in the Tutorials node of the TOC.
 > 
-> Tutorials are 100 – 200 level for an audience new to the service, product, or scenario. Ideally, your tutorials should build on each other using a common theme with the result being a completed customer scenario. Unlike how-to content, they are not open-ended, exhaustive walkthroughs of a feature.
+> Tutorials are 100 – 200 for an audience new to the service, product, or scenario. Ideally, your tutorials should build on each other using a common theme, resulting in a completed customer scenario. Unlike how-to content, they are not open-ended, complete walkthroughs of a feature.
 
 ## Prerequisites
 
@@ -44,13 +44,13 @@ To complete this tutorial, you need:
 ## Log in to the Azure portal
 Log in to the [Azure portal](https://portal.azure.com).
 
-Don’t number H2 and H3 headings. Tutorials are procedure based and customers understand that the sections follow in sequence.
+Don't number H2 and H3 headings. Tutorials are procedure-based, and customers understand that the sections follow in sequence.
 
 ## Create a thing
 Paragraphs here 
 
 Follow these steps to create the thing:
-1. Click the **+ New**  button found on the upper left-hand corner of the Azure portal.
+1. Click the **+ New**  button found in the upper left corner of the Azure portal.
 2. Next step
 3. Next step.
 
@@ -68,9 +68,9 @@ Paragraph and Steps
 [!INCLUDE [aml-delete-resource-group](../../../includes/aml-delete-resource-group.md)]
 
 ## Next Steps
-Tutorials should always have a Next steps H2 that points to the next logical tutorial in a series (one link only here), or, if there are no other tutorials, to some other cool thing the customer can do with the service. Use the blue box format for tutorials and note that you can shorten the H1 in the boxes if the original one doesn’t fit.
+Tutorials should always have a "Next steps" H2 that points to the following logical tutorial in a series (one link only here) or, if there are no other tutorials, to some other cool thing the customer can do with the service. Use the blue box format for tutorials, and note that you can shorten the H1 in the boxes if the original one doesn't fit.
 
 > [!div class="nextstepaction"]
 > [Azure Windows virtual machine tutorials](../../articles/machine-learning/overview-what-is-azure-ml.md)
 
-Do not link to troubleshooting content or FAQs. This implies the customer is going to run into known issues. Either fix these issues beforehand or create a different path to success for users that avoid these problems.
+Do not link to troubleshooting content or FAQs. This implies that the customer is going to run into known issues. Either fix these issues beforehand or create a different path to success for users that avoid these problems.

markdown templates/markdown-template-for-support-articles-symptom-cause-resolution.md

@@ -30,10 +30,10 @@ ms.author: Your MSFT alias or your full email address;semicolon separates two or
 
 ## Summary (Optional, especially when the article is short)
 * *Briefly describe the problem.*
-* *The Summary section is a good place to use different keywords from those in the title, but make sure to not make it very wordy. The sentences should flow well and be easy to understand.*
-* *Exceptions (optional) - List the relevant scenarios that are not covered in this article. For example, ” Linux/OSS scenarios aren't covered in this article”.*
+* *The Summary section is an excellent place to use different keywords from those in the title, but make sure not to make it very wordy. The sentences should flow well and be easy to understand.*
+* *Exceptions (optional) - List the relevant scenarios not covered in this article. For example, ” Linux/OSS scenarios aren't covered in this article”.*
 
-*If it is an article on the billing topic, include the following note (the note below is slightly different than the one at the bottom of this article):*
+*If it is an article on the billing topic, include the following note (the note below is slightly different from the one at the bottom of this article):*
 
 > [!NOTE]
 > If you need more help at any point in this article, please [contact support](https://portal.azure.com/?#blade/Microsoft_Azure_Support/HelpAndSupportBlade) to get your issue resolved quickly.
@@ -48,26 +48,25 @@ ms.author: Your MSFT alias or your full email address;semicolon separates two or
 * *What failed?*
 * *What systems and software would the user have been using?*
 * *What error messages could have been shown?*
-* *Include screenshot if possible.*
+* *Include a screenshot if possible.*
 
 ## Cause
 * *What causes this problem.*
 
 ## Solution
 * *Add screenshots if possible.*
-* *If there are multiple solutions, put them in the order of complexity and provide instructions on how to choose from among them.*
+* *If multiple solutions exist, put them in the order of complexity and provide instructions on choosing from among them.*
 
 | <em>Version 1: Your article is deployment model agnostic</em> | <em>Version 2: Steps for Resource Manager and Classic are largely the same</em> | <em>Version 3: Steps for Resource Manager and Classic are mostly different. <br />In this case, use the <a href="https://github.com/Azure/azure-content-pr/blob/master/contributor-guide/custom-markdown-extensions.md#simple-selectors">Simple Selectors technique in GitHub</a>. <br />Note: VM articles for ARM exceptions and should not use the ARM/Classic selector.</em> |
 |:--- |:--- |:--- |
 | <p><h3>Solution 1</h3><em>(the simplest and most effective)</em></p><ol><li>[Step 1]</li><li>[Step 2]</li></ol><p><h3>Solution 2</h3><em>(the less simple or effective)</em></p><ol><li>[Step 1]</li><li>[Step 2]</li></ol><br /><br /><br /><br /><br /><br /><br /><br /> |<p><h3>Solution 1</h3><em>(the simplest and most effective)</em></p><ol><li>[Step 1]</li><li>If you use the classic deployment model, [do this].<br />If you use the Resource Manager deployment model, [do this].</li><li>[Step 3]</li></ol><p><h3>Solution 2</h3><em>(the less simple or effective)</em></p><ol><li>[Step 1]</li><li>If you use the classic deployment model, [do this].<br />If you use the Resource Manager deployment model, [do this].</li><li>[Step 3]</li></ol> |<img src="media/markdown-template-for-support-articles-symptom-cause-resolution/rm-classic.png" alt="ARM-Classic"><p><h3>Solution 1</h3><em>(the simplest and most effective)</em></p><ol><li>[Step 1]</li><li>[Step 2]</li></ol><p><h3>Solution 2</h3><em>(the less simple or effective)</em></p><ol><li>[Step 1]</li><li>[Step 2]</li></ol><br /><br /><br /><br /> |
 
 ## Next steps
-*Include this section if there are 1 -3 concrete, highly relevant next steps the user should take. Delete if there are no next steps. This is not a place for a list of links. If you include links to next steps, make sure to include text to explain why the next steps are relevant/ important.*
+*Include this section if there are 1 -3 concrete, highly relevant next steps the user should take. Delete if there are no next steps. This is not a place for a list of links. If you include links to the next steps, include text to explain why the next steps are relevant/ important.*
 
-*If it is an article on the billing topic, include the following note (the note below is slightly different than the one at the beginning of this article):*
+*If it is an article on the billing topic, include the following note (the note below is slightly different from the one at the beginning of this article):*
 
 > [!NOTE]
 > If you still have further questions, please [contact support](https://portal.azure.com/?#blade/Microsoft_Azure_Support/HelpAndSupportBlade) to get your issue resolved quickly.
 > 
 > 
-

markdown templates/markdown-template-for-support-articles-troubleshoot.md

@@ -29,8 +29,8 @@ ms.author: Your MSFT alias or your full email address;semicolon separates two or
 [Opening paragraph]
 
 * *Briefly describe the specific issue(s) this article will help troubleshoot and the common root cause(s).*
-* *The opening paragraph is a good place to use different keywords from those in the title, but make sure not to make it very wordy. The sentences should flow well and be easy to understand.*
-* *Exceptions (optional) - List the relevant scenarios that are not covered in this article. For example," Linux/OSS scenarios aren't covered in this article".*
+* *The opening paragraph is an excellent place to use different keywords from those in the title, but make sure not to make it very wordy. The sentences should flow well and be easy to understand.*
+* *Exceptions (optional) - List the relevant scenarios not covered in this article. For example," Linux/OSS scenarios aren't covered in this article."*
 
 These {errors}|{Issues} occur because {a very general reason}.
 
@@ -60,7 +60,7 @@ These {errors}|{Issues} occur because {a very general reason}.
 
 *Here is an example of troubleshooting guidance.*
 
-*In general, if the error does not indicate "the requested VM size is not supported," you can always retry later, as enough resources may have been freed up in the cluster to accommodate your request. If the problem is that the requested VM size is not supported, try a different VM size; otherwise, the only option is to remove the pinning constraint.*
+*Generally, if the error does not indicate "the requested VM size is not supported," you can always retry later, as enough resources may have been freed up in the cluster to accommodate your request. If the problem is that the requested VM size is not supported, try a different VM size; otherwise, the only option is to remove the pinning constraint.*
 
 ## Troubleshooting steps
 *List the solutions in the order of usability and simplicity, meaning the simplest, most effective, and most useful solution should go first.*