From 9e603d4befa01824a66f7b57c0a8e0b07789b03c Mon Sep 17 00:00:00 2001 From: Tyson Nevil Date: Thu, 27 Oct 2016 16:26:07 -0700 Subject: [PATCH 1/4] updating templates --- .../markdown-template-for-new-articles.md | 211 ++++++++---------- ...pport-articles-symptom-cause-resolution.md | 100 +++++---- ...plate-for-support-articles-troubleshoot.md | 161 ++++++------- ...achines-ps-template-compare-sm-arm-task.md | 78 ++++--- 4 files changed, 273 insertions(+), 277 deletions(-) diff --git a/markdown templates/markdown-template-for-new-articles.md b/markdown templates/markdown-template-for-new-articles.md index a0cfd0c8eea03..027bd9ff82fb0 100644 --- a/markdown templates/markdown-template-for-new-articles.md +++ b/markdown templates/markdown-template-for-new-articles.md @@ -1,113 +1,98 @@ - - - - -# Markdown template (article Heading 1 or H1): Heading at the top of the article - -To copy the markdown from this template, copy the article in your local repo, or click the Raw button in the GitHub UI and copy the markdown. - - ![Alt text; do not leave blank. Describe image.][8] - -Intro paragraph: Lorem dolor amet, adipiscing elit. Phasellus interdum nulla risus, lacinia porta nisl imperdiet sed. Mauris dolor mauris, tempus sed lacinia nec, euismod non felis. Nunc semper porta ultrices. Maecenas neque nulla, condimentum vitae ipsum sit amet, dignissim aliquet nisi. - -## Heading 2 (H2) - -Aenean sit amet leo nec purus placerat fermentum ac gravida odio. Aenean tellus lectus, faucibus in rhoncus in, faucibus sed urna. volutpat mi id purus ultrices iaculis nec non neque. [Link text for link outside of azure.microsoft.com](http://weblogs.asp.net/scottgu). Nullam dictum dolor at aliquam pharetra. Vivamus ac hendrerit mauris [example link text for link to an article in a service folder](../articles/expressroute/expressroute-bandwidth-upgrade.md). - -I get 10 times more traffic from [Google] [gog] than from [Yahoo] [yah] or [MSN] [msn]. - -> [AZURE.NOTE] Indented note text. The word 'note' will be added during publication. Ut eu pretium lacus. Nullam purus est, iaculis sed est vel, euismod vehicula odio. Curabitur lacinia, erat tristique iaculis rutrum, erat sem sodales nisi, eu condimentum turpis nisi a purus. - -1. Aenean sit amet leo nec **Purus** placerat fermentum ac gravida odio. - -2. Aenean tellus lectus, faucius in **Rhoncus** in, faucibus sed urna. Suspendisse volutpat mi id purus ultrices iaculis nec non neque. - - ![Alt text; do not leave blank. Collector car in racing red.][5] - -3. Nullam dictum dolor at aliquam pharetra. Vivamus ac hendrerit mauris. Sed dolor dui, condimentum et varius a, vehicula at nisl. - - ![Alt text; do not leave blank][6] - - -Suspendisse volutpat mi id purus ultrices iaculis nec non neque. Nullam dictum dolor at aliquam pharetra. Vivamus ac hendrerit mauris. Otrus informatus: [Link 1 to another azure.microsoft.com documentation topic](virtual-machines-windows-hero-tutorial.md) - -## Heading (H2) - -Ut eu pretium lacus. Nullam purus est, iaculis sed est vel, euismod vehicula odio. - -1. Curabitur lacinia, erat tristique iaculis rutrum, erat sem sodales nisi, eu condimentum turpis nisi a purus. - - - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions: - (NSDictionary *)launchOptions - { - // Register for remote notifications - [[UIApplication sharedApplication] registerForRemoteNotificationTypes: - UIRemoteNotificationTypeAlert | UIRemoteNotificationTypeBadge | UIRemoteNotificationTypeSound]; - return YES; - } - -2. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia. - - // Because toast alerts don't work when the app is running, the app handles them. - // This uses the userInfo in the payload to display a UIAlertView. - - (void)application:(UIApplication *)application didReceiveRemoteNotification: - (NSDictionary *)userInfo { - NSLog(@"%@", userInfo); - UIAlertView *alert = [[UIAlertView alloc] initWithTitle:@"Notification" message: - [userInfo objectForKey:@"inAppMessage"] delegate:nil cancelButtonTitle: - @"OK" otherButtonTitles:nil, nil]; - [alert show]; - } - - - > [AZURE.NOTE] Duis sed diam non nisl molestie pharetra eget a est. [Link 2 to another azure.microsoft.com documentation topic](web-sites-custom-domain-name.md) - - -Quisque commodo eros vel lectus euismod auctor eget sit amet leo. Proin faucibus suscipit tellus dignissim ultrices. - -## Heading 2 (H2) - -1. Maecenas sed condimentum nisi. Suspendisse potenti. - - + Fusce - + Malesuada - + Sem - -2. Nullam in massa eu tellus tempus hendrerit. - - ![Alt text; do not leave blank. Example of a Channel 9 video.][7] - -3. Quisque felis enim, fermentum ut aliquam nec, pellentesque pulvinar magna. - - - - - -## Next steps - -Vestibul ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae; Nullam ultricies, ipsum vitae volutpat hendrerit, purus diam pretium eros, vitae tincidunt nulla lorem sed turpis: [Link 3 to another azure.microsoft.com documentation topic](storage-whatis-account.md). - - -[5]: ./media/markdown-template-for-new-articles/octocats.png -[6]: ./media/markdown-template-for-new-articles/pretty49.png -[7]: ./media/markdown-template-for-new-articles/channel-9.png -[8]: ./media/markdown-template-for-new-articles/copytemplate.png - - -[gog]: http://google.com/ -[yah]: http://search.yahoo.com/ -[msn]: http://search.msn.com/ +--- +title: Page title that displays in the browser tab and search results | Microsoft Docs +description: Article description that will be displayed on landing pages and in most search results +services: service-name +documentationcenter: dev-center-name +author: GitHub-alias-of-only-one-author +manager: manager-alias + + +ms.service: required +ms.devlang: may be required +ms.topic: article +ms.tgt_pltfrm: may be required +ms.workload: required +ms.date: mm/dd/yyyy +ms.author: Your MSFT alias or your full email address;semicolon separates two or more aliases + +--- +# Markdown template for Azure on Microsoft Docs + +Your article should have only on H1 heading, which you create with a single # sign. The the H1 heading should always be followed by a descriptive paragraph that helps the customer understand what the article is about. It should contain keywords you think customers would use to search for this piece of content. Do not start the article with a note or tip - always start with an introductory paragraph. + +## Headings + +Two ## signs create an H2 heading - if your article needs to be structured with headings below the H1, you need to have at least TWO H2 headings. + +H2 headings are rendered on the page as an automatic on-page TOC. Do not hand-code article navigation in an article. Use the H2 headings to do that. + +Within an H2 section, you can use three ### signs to create H3 headings. In our content, try to avoid going deeper than 3 heading layers - the headings are often hard to distinguish on the rendered page. + +## Images +You can use images throughout a technical article. Make sure you include alt text for all your images. This helps accessibility and discoverability. + + ![Alt text; do not leave blank. Describe image.][8] + + ![Alt text; do not leave blank. Collector car in racing red.][5] + +## Linking +Your article will most likely contain links. Here's a sample link to a target not on the docs.microsoft.com site: + + [Link text for link outside of azure.microsoft.com](http://weblogs.asp.net/scottgu). + +Here's a sample link to another technical article in the azure-docs-pr repository: + + [example link text for link to an article in a service folder](../expressroute/expressroute-bandwidth-upgrade.md). + +You can also use so-called reference style links where you define the links at the bottom of the article, and reference them like this: + + I get 10 times more traffic from [Google][gog] than from [Yahoo][yah] or [MSN][msn]. + +For information about linking, see the [linking guidance](../contributor-guide/create-links-markdown.md) + +## Notes and tips +You should use notes and tips judiciously. A little bit goes a long way. + +> [!NOTE] +> Note text. + +> [!TIP] +> Tip text. + +> [!IMPORTANT] +> +## Lists + +A simple numbered list in markdown creates a numbered list on your published page. + +1. First step. +2. Second step. +3. Third step. + +Use hyphens to create unordered lists: + +- Item +- Item +- Item + + +## Next steps +Every topic should end with 1 to 3 concrete, action oriented next steps and links to the next logical piece of content to keep the customer engaged. + +- See the [content quality guidelines](../contributor-guide/contributor-guide-pr-criteria.md#non-blocking-content-quality-items) for an example of what a good next steps section looks like. + +- Review the [custom markdown extensions](../contributor-guide/custom-markdown-extensions.md) we use for videos, reusable content, selectors, and other content features. + +- Make sure your articles meet [the content quality guidelines](../contributor-guide/contributor-guide-pr-criteria.md) before you sign-off on a PR. + + + +[5]: ./media/markdown-template-for-new-articles/octocats.png +[6]: ./media/markdown-template-for-new-articles/pretty49.png +[7]: ./media/markdown-template-for-new-articles/channel-9.png +[8]: ./media/markdown-template-for-new-articles/copytemplate.png + + +[gog]: http://google.com/ +[yah]: http://search.yahoo.com/ +[msn]: http://search.msn.com/ diff --git a/markdown templates/markdown-template-for-support-articles-symptom-cause-resolution.md b/markdown templates/markdown-template-for-support-articles-symptom-cause-resolution.md index f19920bb92e86..1eeedabed94e2 100644 --- a/markdown templates/markdown-template-for-support-articles-symptom-cause-resolution.md +++ b/markdown templates/markdown-template-for-support-articles-symptom-cause-resolution.md @@ -1,69 +1,73 @@ - - - - +--- +title: Page title that displays in the browser tab and search results +description: Article description that will be displayed on landing pages and in most search results +services: service-name +documentationcenter: dev-center-name +author: GitHub-alias-of-only-one-author +manager: manager-alias +editor: '' +tags: comma-separates-additional-tags-if-required + +ms.service: required +ms.devlang: may be required +ms.topic: article +ms.tgt_pltfrm: may be required +ms.workload: required +ms.date: mm/dd/yyyy +ms.author: Your MSFT alias or your full email address;semicolon separates two or more + +--- # Title (Maximum 120 characters, target the primary keyword) +*Use 2-3 secondary keywords in the description.* -_Use 2-3 secondary keywords in the description._ - -_Select one of the following disclaimers depending on your scenario. If your article is deployment model agnostic, ignore this._ +*Select one of the following disclaimers depending on your scenario. If your article is deployment model agnostic, ignore this.* -[AZURE.INCLUDE [learn-about-deployment-models](../../includes/learn-about-deployment-models-rm-include.md)] classic deployment model. +[!INCLUDE [learn-about-deployment-models](../../includes/learn-about-deployment-models-rm-include.md)] classic deployment model. -[AZURE.INCLUDE [learn-about-deployment-models](../../includes/learn-about-deployment-models-classic-include.md)] +[!INCLUDE [learn-about-deployment-models](../../includes/learn-about-deployment-models-classic-include.md)] -[AZURE.INCLUDE [learn-about-deployment-models](../../learn-about-deployment-models-both-include.md)] +[!INCLUDE [learn-about-deployment-models](../../learn-about-deployment-models-both-include.md)] ## 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”.* -- _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”._ +*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 than the one at the bottom of this article):_ -> [AZURE.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. +> [!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. +> +> -_If it is NOT a billing article, use the following reference:_ -[AZURE.INCLUDE [support-disclaimer](../../includes/support-disclaimer.md)] +*If it is NOT a billing article, use the following reference:* +[!INCLUDE [support-disclaimer](../../includes/support-disclaimer.md)] ## Symptom - -- _What actions would the user be trying to complete?_ -- _What failed?_ -- _What systems and software would the user have been using?_ -- _What error messages could have been shown?_ -- _Include screenshot if possible._ +* *What actions would the user be trying to complete?* +* *What failed?* +* *What systems and software would the user have been using?* +* *What error messages could have been shown?* +* *Include screenshot if possible.* ## Cause - -- _What causes this problem._ +* *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._ +* *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.* | Version 1: Your article is deployment model agnostic | Version 2: Steps for Resource Manager and Classic are largely the same | Version 3: Steps for Resource Manager and Classic are mostly different.
In this case, use the Simple Selectors technique in Github.
Note: VM articles for ARM exceptions and should not use the ARM/Classic selector. | -|:------------------------------------------------------|:-----------------------------------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -|

Solution 1

(the simplest and most effective)

  1. [Step 1]
  2. [Step 2]

Solution 2

(the less simple or effective)

  1. [Step 1]
  2. [Step 2]








|

Solution 1

(the simplest and most effective)

  1. [Step 1]
  2. If you use the classic deployment model, [do this].
    If you use the Resource Manager deployment model, [do this].
  3. [Step 3]

Solution 2

(the less simple or effective)

  1. [Step 1]
  2. If you use the classic deployment model, [do this].
    If you use the Resource Manager deployment model, [do this].
  3. [Step 3]
| ARM-Classic

Solution 1

(the simplest and most effective)

  1. [Step 1]
  2. [Step 2]

Solution 2

(the less simple or effective)

  1. [Step 1]
  2. [Step 2]




| +|:--- |:--- |:--- | +|

Solution 1

(the simplest and most effective)

  1. [Step 1]
  2. [Step 2]

Solution 2

(the less simple or effective)

  1. [Step 1]
  2. [Step 2]








|

Solution 1

(the simplest and most effective)

  1. [Step 1]
  2. If you use the classic deployment model, [do this].
    If you use the Resource Manager deployment model, [do this].
  3. [Step 3]

Solution 2

(the less simple or effective)

  1. [Step 1]
  2. If you use the classic deployment model, [do this].
    If you use the Resource Manager deployment model, [do this].
  3. [Step 3]
|ARM-Classic

Solution 1

(the simplest and most effective)

  1. [Step 1]
  2. [Step 2]

Solution 2

(the less simple or effective)

  1. [Step 1]
  2. [Step 2]




| ## 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 next steps, make sure to 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):* + +> [!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. +> +> -_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):_ -> [AZURE.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. diff --git a/markdown templates/markdown-template-for-support-articles-troubleshoot.md b/markdown templates/markdown-template-for-support-articles-troubleshoot.md index f6258a161116d..106fbd5a234f1 100644 --- a/markdown templates/markdown-template-for-support-articles-troubleshoot.md +++ b/markdown templates/markdown-template-for-support-articles-troubleshoot.md @@ -1,76 +1,85 @@ - - - - -# Title (Maximum 120 characters, target the primary keyword) - -_Use 2-3 secondary keywords in the description._ - -_Select one of the following disclaimers depending on your scenario. If your article is deployment model agnostic, ignore this._ - -[AZURE.INCLUDE [learn-about-deployment-models](../../includes/learn-about-deployment-models-rm-include.md)] classic deployment model. - -[AZURE.INCLUDE [learn-about-deployment-models](../../includes/learn-about-deployment-models-classic-include.md)] - -[AZURE.INCLUDE [learn-about-deployment-models](../../learn-about-deployment-models-both-include.md)] - -[Opening paragraph] -- _Briefly describe the specific issue(s) that 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 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”._ - -These {errors}|{Issues} occur because {a very general reason}. - -_Here is an example of an opening paragraph._ - -_When you try to connect to Azure SQL Database, the common connection errors you encounter are:_ -- _The login failed for the user. The password change failed._ -- _Password validation failed._ -- _Failed to authorize access to the specified subscription._ - -_These errors occur because you don’t have permission to access the data source._ - -_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):_ -> [AZURE.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. - -_If it is NOT a billing article, include the following reference:_ -[AZURE.INCLUDE [support-disclaimer](../../includes/support-disclaimer.md)] - -## Troubleshooting guidance (optional) -- _Use this section when the guidance applies across the board._ -- _Don’t go into details. Keep it high level to serve as a guidance._ - -_Here is an example of a troubleshooting guidance._ - -_In general, as long as the error does not indicate "the requested VM size is not supported", you can always retry at a later time, as enough resource may have been freed up in the cluster to accommodate your request. If the problem is 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, the most effective and useful solution should go first._ - -_Select one of the versions that apply to your situation._ - -| Version 1: Your article is deployment model agnostic | Version 2: Steps for Resource Manager and Classic are largely the same | Version 3: Steps for Resource Manager and Classic are mostly different.
In this case, use the Simple Selectors technique in Github.
Note: VM articles for ARM are exceptions and should not use the ARM/Classic selector. | -|:------------------------------------------------------|:-----------------------------------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -|

[Issue 1] \| [Error 1]

Cause

[Cause details]

Solution 1

(the simplest and most effective)

  1. [Step 1]
  2. [Step 2]

Solution 2

(the less simple or effective)

  1. [Step 1]
  2. [Step 2]

[Issue 2] \| [Error 2]

Cause

[Cause details]

Solution 1

(the simplest and most effective)

  1. [Step 1]
  2. [Step 2]

Solution 2

(the simplest and most effective)

  1. [Step 1]
  2. [Step 2]
















|

[Issue 1] \| [Error 1]

Cause

[Cause details]

Solution 1

(the simplest and most effective)

  1. [Step 1]
  2. If you use the classic deployment model, [do this].
    If you use the Resource Manager deployment model, [do this].
  3. [Step 3]

Solution 2

(the less simple or effective)

  1. [Step 1]
  2. If you use the classic deployment model, [do this].
    If you use the Resource Manager deployment model, [do this].
  3. [Step 3]

[Issue 2] \| [Error 2]

Cause

[Cause details]

Solution 1

(the simplest and most effective)

  1. [Step 1]
  2. If you use the classic deployment model, [do this].
    If you use the Resource Manager deployment model, [do this].
  3. [Step 3]

Solution 2

(the simplest and most effective)

  1. [Step 1]
  2. If you use the classic deployment model, [do this].
    If you use the Resource Manager deployment model, [do this].
  3. [Step 3]
| ARM-Classic

[Issue 1] \| [Error 1]

Cause

[Cause details]

Solution 1

(the simplest and most effective)

  1. [Step 1]
  2. [Step 2]

Solution 2

(the less simple or effective)

  1. [Step 1]
  2. [Step 2]

[Issue 2] \| [Error 2]

Cause

[Cause details]

Solution 1

(the simplest and most effective)

  1. [Step 1]
  2. [Step 2]

Solution 2

(the simplest and most effective)

  1. [Step 1]
  2. [Step 2]












| - - -## 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._ - -_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):_ -> [AZURE.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. +--- +title: 42 characters followed by | Microsoft Docs +description: Displayed in search engines under the title. You have more room here, use more keywords and a more descriptive explanation than the title +services: service-name +documentationcenter: dev-center-name +author: GitHub-alias-of-only-one-author +manager: manager-alias +editor: '' +tags: top-support-issue + +ms.service: required +ms.devlang: may be required +ms.topic: article +ms.tgt_pltfrm: may be required +ms.workload: required +ms.date: mm/dd/yyyy +ms.author: Your MSFT alias or your full email address;semicolon separates two or more + +--- +# Title (Maximum 120 characters, target the primary keyword) +*Use 2-3 secondary keywords in the description.* + +*Select one of the following disclaimers depending on your scenario. If your article is deployment model agnostic, ignore this.* + +[!INCLUDE [learn-about-deployment-models](../../includes/learn-about-deployment-models-rm-include.md)] classic deployment model. + +[!INCLUDE [learn-about-deployment-models](../../includes/learn-about-deployment-models-classic-include.md)] + +[!INCLUDE [learn-about-deployment-models](../../learn-about-deployment-models-both-include.md)] + +[Opening paragraph] + +* *Briefly describe the specific issue(s) that 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 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”.* + +These {errors}|{Issues} occur because {a very general reason}. + +*Here is an example of an opening paragraph.* + +*When you try to connect to Azure SQL Database, the common connection errors you encounter are:* + +* *The login failed for the user. The password change failed.* +* *Password validation failed.* +* *Failed to authorize access to the specified subscription.* + +*These errors occur because you don’t have permission to access the data source.* + +*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):* + +> [!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. +> +> + +*If it is NOT a billing article, include the following reference:* +[!INCLUDE [support-disclaimer](../../includes/support-disclaimer.md)] + +## Troubleshooting guidance (optional) +* *Use this section when the guidance applies across the board.* +* *Don’t go into details. Keep it high level to serve as a guidance.* + +*Here is an example of a troubleshooting guidance.* + +*In general, as long as the error does not indicate "the requested VM size is not supported", you can always retry at a later time, as enough resource may have been freed up in the cluster to accommodate your request. If the problem is 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, the most effective and useful solution should go first.* + +*Select one of the versions that apply to your situation.* + +| Version 1: Your article is deployment model agnostic | Version 2: Steps for Resource Manager and Classic are largely the same | Version 3: Steps for Resource Manager and Classic are mostly different.
In this case, use the Simple Selectors technique in Github.
Note: VM articles for ARM are exceptions and should not use the ARM/Classic selector. | +|:--- |:--- |:--- | +|

[Issue 1] \ |[Error 1]

Cause

[Cause details]

Solution 1

(the simplest and most effective)

  1. [Step 1]
  2. [Step 2]

Solution 2

(the less simple or effective)

  1. [Step 1]
  2. [Step 2]

[Issue 2] \ |[Error 2]

Cause

[Cause details]

Solution 1

(the simplest and most effective)

  1. [Step 1]
  2. [Step 2]

Solution 2

(the simplest and most effective)

  1. [Step 1]
  2. [Step 2]
















| + +## 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.* + +*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):* + +> [!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. +> +> + diff --git a/markdown templates/virtual-machines-ps-template-compare-sm-arm-task.md b/markdown templates/virtual-machines-ps-template-compare-sm-arm-task.md index 6bf01188b29b6..36e2e8bea532a 100644 --- a/markdown templates/virtual-machines-ps-template-compare-sm-arm-task.md +++ b/markdown templates/virtual-machines-ps-template-compare-sm-arm-task.md @@ -11,20 +11,20 @@ Pay attention to spacing and indents. They affect formatting. # Use Azure PowerShell to [task] - This article shows you how to [task], using commands from both the Azure module and the Azure Resource Manager module. This is intended to help you learn the new commands as well as migrate existing scripts to the new commands. ## Prerequisite: Install a Recent Version of Azure PowerShell - If you haven't done so already, install at least the [version number] version of Azure PowerShell on your local computer. If you use an earlier version, it won't have the Azure Resource Manager cmdlets described in this article. For details, see: - -- [How to install and configure Azure PowerShell](install-configure-powershell.md) for instructions on setting up Azure PowerShell. -- [Using Windows PowerShell with Resource Manager](powershell-azure-resource-manager.md) for basics on using Resource Manager. -> [AZURE.NOTE] Most tasks require you to use an administrator-level Azure PowerShell command prompt. +* [How to install and configure Azure PowerShell](install-configure-powershell.md) for instructions on setting up Azure PowerShell. +* [Using Windows PowerShell with Resource Manager](powershell-azure-resource-manager.md) for basics on using Resource Manager. -## Command Comparison +> [!NOTE] +> Most tasks require you to use an administrator-level Azure PowerShell command prompt. +> +> +## Command Comparison This [table | section] shows the command syntax. -Service Management | Resource Manager ----|---- -`syntax` | `syntax` - +| Service Management | Resource Manager | +| --- | --- | +| `syntax` |`syntax` | - + [Short intro sentence about the command. Omit if there's really nothing to say. But if it uses approaches such a the pipeline, explain that]: - [command string] + [command string] ## Script Examples - Here's an example that uses [cmdlet names)] to [task]. It includes commands that: -- [short verb, uses, has, is, etc] -- [next short verb] +* [short verb, uses, has, is, etc] +* [next short verb] It includes the following variables: -- [variable 1] -- [variable 2] +* [variable 1] +* [variable 2] - $family="Windows Server 2012 R2 Datacenter" - $image=Get-AzureVMImage | where { $_.ImageFamily -eq $family } | sort PublishedDate -Descending | select -ExpandProperty ImageName -First 1 - $vmname="AZDC1" - $vmsize="Medium" - $vm1=New-AzureVMConfig -Name $vmname -InstanceSize $vmsize -ImageName $image - - $cred=Get-Credential -Message "Type the name and password of the local administrator account." - $vm1 | Add-AzureProvisioningConfig -Windows -AdminUsername $cred.GetNetworkCredential().Username -Password $cred.GetNetworkCredential().Password - - $vm1 | Set-AzureSubnet -SubnetNames "BackEnd" - - $vm1 | Set-AzureStaticVNetIP -IPAddress 192.168.244.4 - - $disksize=20 - $disklabel="DCData" - $lun=0 - $hcaching="None" - $vm1 | Add-AzureDataDisk -CreateNew -DiskSizeInGB $disksize -DiskLabel $disklabel -LUN $lun -HostCaching $hcaching - - $svcname="Azure-TailspinToys" - $vnetname="AZDatacenter" - New-AzureVM –ServiceName $svcname -VMs $vm1 -VNetName $vnetname + $family="Windows Server 2012 R2 Datacenter" + $image=Get-AzureVMImage | where { $_.ImageFamily -eq $family } | sort PublishedDate -Descending | select -ExpandProperty ImageName -First 1 + $vmname="AZDC1" + $vmsize="Medium" + $vm1=New-AzureVMConfig -Name $vmname -InstanceSize $vmsize -ImageName $image + + $cred=Get-Credential -Message "Type the name and password of the local administrator account." + $vm1 | Add-AzureProvisioningConfig -Windows -AdminUsername $cred.GetNetworkCredential().Username -Password $cred.GetNetworkCredential().Password + + $vm1 | Set-AzureSubnet -SubnetNames "BackEnd" + + $vm1 | Set-AzureStaticVNetIP -IPAddress 192.168.244.4 + + $disksize=20 + $disklabel="DCData" + $lun=0 + $hcaching="None" + $vm1 | Add-AzureDataDisk -CreateNew -DiskSizeInGB $disksize -DiskLabel $disklabel -LUN $lun -HostCaching $hcaching + + $svcname="Azure-TailspinToys" + $vnetname="AZDatacenter" + New-AzureVM –ServiceName $svcname -VMs $vm1 -VNetName $vnetname ## Additional Resources From 3db21ede614c2330d2547645ff38b8bf7a145ce6 Mon Sep 17 00:00:00 2001 From: Tyson Nevil Date: Thu, 27 Oct 2016 16:43:40 -0700 Subject: [PATCH 2/4] update template --- .../markdown-template-for-new-articles.md | 42 +++++++++++++------ 1 file changed, 29 insertions(+), 13 deletions(-) diff --git a/markdown templates/markdown-template-for-new-articles.md b/markdown templates/markdown-template-for-new-articles.md index 027bd9ff82fb0..615c2eb83038b 100644 --- a/markdown templates/markdown-template-for-new-articles.md +++ b/markdown templates/markdown-template-for-new-articles.md @@ -18,7 +18,7 @@ ms.author: Your MSFT alias or your full email address;semicolon separates two or --- # Markdown template for Azure on Microsoft Docs -Your article should have only on H1 heading, which you create with a single # sign. The the H1 heading should always be followed by a descriptive paragraph that helps the customer understand what the article is about. It should contain keywords you think customers would use to search for this piece of content. Do not start the article with a note or tip - always start with an introductory paragraph. +Your article should have only one H1 heading, which you create with a single # sign. The the H1 heading should always be followed by a descriptive paragraph that helps the customer understand what the article is about. It should contain keywords you think customers would use to search for this piece of content. Do not start the article with a note or tip - always start with an introductory paragraph. ## Headings @@ -31,27 +31,45 @@ Within an H2 section, you can use three ### signs to create H3 headings. In our ## Images You can use images throughout a technical article. Make sure you include alt text for all your images. This helps accessibility and discoverability. - ![Alt text; do not leave blank. Describe image.][8] +This image of the GitHub Octocats uses in-line image references: - ![Alt text; do not leave blank. Collector car in racing red.][5] + ![GitHub Octocats using inline link](./media/markdown-template-for-new-articles/octocats.png) + +The sample markdown looks like this: +``` +![GitHub Octocats using inline link](./media/markdown-template-for-new-articles/octocats.png) +``` + +This second image of the octocats uses reference style syntax, where you define the target as "5" and at the bottom of the article, and you list the path to image 5 in a reference section. + ![GitHub Octocats using ref style link][5] + + The sample markdown looks like this: + ``` + ![GitHub Octocats image][5] + + + [5]: ./media/markdown-template-for-new-articles/octocats.png + ``` ## Linking -Your article will most likely contain links. Here's a sample link to a target not on the docs.microsoft.com site: +Your article will most likely contain links. Here's sample markdown for a link to a target that is not on the docs.microsoft.com site: - [Link text for link outside of azure.microsoft.com](http://weblogs.asp.net/scottgu). + [link text](url) + [Scott Guthrie's blog](http://weblogs.asp.net/scottgu) -Here's a sample link to another technical article in the azure-docs-pr repository: +Here's sample markdown for a link to another technical article in the azure-docs-pr repository: - [example link text for link to an article in a service folder](../expressroute/expressroute-bandwidth-upgrade.md). + [link text](../service-directory/article-name.md) + [ExpressRoute circuits and routing domains](../expressroute/expressroute-circuit-peerings.md) You can also use so-called reference style links where you define the links at the bottom of the article, and reference them like this: I get 10 times more traffic from [Google][gog] than from [Yahoo][yah] or [MSN][msn]. -For information about linking, see the [linking guidance](../contributor-guide/create-links-markdown.md) +For more information about linking, see the [linking guidance](../contributor-guide/create-links-markdown.md) ## Notes and tips -You should use notes and tips judiciously. A little bit goes a long way. +You should use notes and tips judiciously. A little bit goes a long way. Put the text of the note or tip on the line after the custom markdown extension. > [!NOTE] > Note text. @@ -60,7 +78,8 @@ You should use notes and tips judiciously. A little bit goes a long way. > Tip text. > [!IMPORTANT] -> +> Important text. + ## Lists A simple numbered list in markdown creates a numbered list on your published page. @@ -88,9 +107,6 @@ Every topic should end with 1 to 3 concrete, action oriented next steps and link [5]: ./media/markdown-template-for-new-articles/octocats.png -[6]: ./media/markdown-template-for-new-articles/pretty49.png -[7]: ./media/markdown-template-for-new-articles/channel-9.png -[8]: ./media/markdown-template-for-new-articles/copytemplate.png [gog]: http://google.com/ From 533b5cb26bf580657c7fbac31d43db02f2930729 Mon Sep 17 00:00:00 2001 From: Tyson Nevil Date: Thu, 27 Oct 2016 16:45:10 -0700 Subject: [PATCH 3/4] update template --- markdown templates/markdown-template-for-new-articles.md | 1 + 1 file changed, 1 insertion(+) diff --git a/markdown templates/markdown-template-for-new-articles.md b/markdown templates/markdown-template-for-new-articles.md index 615c2eb83038b..e1ca046d78af8 100644 --- a/markdown templates/markdown-template-for-new-articles.md +++ b/markdown templates/markdown-template-for-new-articles.md @@ -41,6 +41,7 @@ The sample markdown looks like this: ``` This second image of the octocats uses reference style syntax, where you define the target as "5" and at the bottom of the article, and you list the path to image 5 in a reference section. + ![GitHub Octocats using ref style link][5] The sample markdown looks like this: From dfee9fb7668ebef896b3fb68ba1e682a04664ed4 Mon Sep 17 00:00:00 2001 From: Tyson Nevil Date: Thu, 27 Oct 2016 16:46:06 -0700 Subject: [PATCH 4/4] update template --- markdown templates/markdown-template-for-new-articles.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/markdown templates/markdown-template-for-new-articles.md b/markdown templates/markdown-template-for-new-articles.md index e1ca046d78af8..e39d634851378 100644 --- a/markdown templates/markdown-template-for-new-articles.md +++ b/markdown templates/markdown-template-for-new-articles.md @@ -72,6 +72,7 @@ For more information about linking, see the [linking guidance](../contributor-gu ## Notes and tips You should use notes and tips judiciously. A little bit goes a long way. Put the text of the note or tip on the line after the custom markdown extension. +``` > [!NOTE] > Note text. @@ -80,6 +81,7 @@ You should use notes and tips judiciously. A little bit goes a long way. Put the > [!IMPORTANT] > Important text. +``` ## Lists