Skip to content

Commit

Permalink
Merge pull request MicrosoftDocs#48 from tysonn/master
Browse files Browse the repository at this point in the history 
updating templates
  • Loading branch information
@tynevi
tynevi authored Oct 28, 2016
2 parents 0ba945d + dfee9fb commit 25e5273
Show file tree
Hide file tree
Showing 4 changed files with 292 additions and 277 deletions.
230 changes: 117 additions & 113 deletions markdown templates/markdown-template-for-new-articles.md
View file
Original file line number Diff line number Diff line change
@@ -1,113 +1,117 @@
<properties
pageTitle="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"
authors="GitHub-alias-of-only-one-author"
manager="manager-alias"
editor=""/>

<tags
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"/>

# 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 <i>nisl molestie</i> 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.




<!--Every topic should have next steps and links to the next logical set of content to keep the customer engaged-->
## 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).

<!--Image references-->
[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

<!--Reference style links - using these makes the source content way more readable than using inline links-->
[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 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

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.

This image of the GitHub Octocats uses in-line image references:

![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]
<!--Image references-->
[5]: ./media/markdown-template-for-new-articles/octocats.png
```

## Linking
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](url)
[Scott Guthrie's blog](http://weblogs.asp.net/scottgu)

Here's sample markdown for a link to another technical article in the azure-docs-pr repository:

[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 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. Put the text of the note or tip on the line after the custom markdown extension.

```
> [!NOTE]
> Note text.
> [!TIP]
> Tip text.
> [!IMPORTANT]
> Important text.
```

## 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.


<!--Image references-->
[5]: ./media/markdown-template-for-new-articles/octocats.png

<!--Reference style links - using these makes the source content way more readable than using inline links-->
[gog]: http://google.com/
[yah]: http://search.yahoo.com/
[msn]: http://search.msn.com/
100 changes: 52 additions & 48 deletions ...wn templates/markdown-template-for-support-articles-symptom-cause-resolution.md
View file
Original file line number Diff line number Diff line change
@@ -1,69 +1,73 @@
<properties
pageTitle="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"
authors="GitHub-alias-of-only-one-author"
manager="manager-alias"
editor=""
tags="comma-separates-additional-tags-if-required"/>

<tags
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: 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.*

| <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 /> |
|:--- |:--- |:--- |
| <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 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.
Loading

0 comments on commit 25e5273

Please sign in to comment.