Skip to content

Commit 4e4a476

Browse files
barbkessbarbkess
committed
template updates
1 parent 55ac415 commit 4e4a476

2 files changed

Lines changed: 88 additions & 85 deletions

File tree

‎contributor-guide/templates/tutorial-template-annotated-example.md‎

Lines changed: 28 additions & 85 deletions
Original file line numberDiff line numberDiff line change
@@ -1,97 +1,43 @@
1-
---
2-
title:="Deploy an ASP.NET web app to App Service | Microsoft Docs"
3-
description: "This tutorial shows how to deploy an ASP.NET web application to a web app in Azure App Service by using Visual Studio 2015. "
4-
services: "app-service"
5-
documentationCenter: ""
6-
authors: "CarlRabeler"
7-
manager: "jhubbard"
8-
editor: ""/>
9-
10-
ms.service="app-service"
11-
ms.devlang="NA"
12-
ms.custom: "NA"
13-
ms.topic="article"
14-
ms.tgt_pltfrm="NA"
15-
ms.workload="NA"
16-
ms.date="10/20/2016"
17-
ms.author="carlrab;barbkess"/>
18-
191
---
202
<!------------------
21-
This topic is annotated with TEMPLATE guidelines for TUTORIAL TOPICS.
22-
23-
24-
Metadata guidelines
25-
26-
title
27-
60 characters or less. Tells users clearly what they will do (deploy an ASP.NET web app to App Service). Not the same as H1. It's 60 characters or fewer including all characters between the quotes and the Microsoft Docs site identifier.
28-
29-
description
30-
115-145 characters. Duplicate of the first sentence in the introduction. This is the abstract of the article that displays under the title when searching in Bing or Google.
31-
32-
Example: "This tutorial shows how to deploy an ASP.NET web application to a web app in Azure App Service by using Visual Studio 2015."
33-
------------------>
34-
35-
<!----------------
36-
37-
TEMPLATE GUIDELINES for tutorial topics
38-
39-
The tutorial topic shows users how to solve a problem using a product or service. It includes the prerequisites and steps users need to be successful.
403

41-
It is a "solve a problem" topic, not a "learn concepts" topic.
4+
This is an annotated example of a tutorial with high CSAT (https://docs.microsoft.com/en-us/azure/app-service-web/web-sites-dotnet-get-started).
425

43-
DO include this:
44-
• What users will do
45-
• What they will create or accomplish by the end of the tutorial
46-
• Time estimate
47-
• Optional but useful: Include a diagram or video. Diagrams help users see the big picture of what they are doing. A video of the steps can be used by customers as an alternative to following the steps in the topic.
48-
• Prerequisites: Technical expertise and software requirements
49-
• End-to-end steps. At the end, include next steps to deeper or related tutorials so users can learn more about the service
6+
Tutorials show users how to solve a problem. They include prerequisites and steps. They are not "learn concepts" topics.
507

51-
DON'T include this:
52-
• Conceptual info about the service. This info is in overview topics that you can link to in the prerequisites section if necessary
538

54-
------------------->
55-
56-
<!------------------
57-
GUIDELINES for the H1
9+
GUIDELINES for H1
10+
The H1 is the top heading in the article. It tells users what they will do. Use strong keywords: deploy, ASP.NET, web app, App Service, Visual Studio, as you see below.
5811
59-
The H1 should answer the question "What will I do in this topic?" Write the H1 heading in conversational language and use search keywords as much as possible. Since this is a "solve a problem" topic, make sure the title indicates that. Use a strong, specific verb like "Deploy."
60-
61-
Heading must use an industry standard term. If your feature is a proprietary name like "Elastic database pools", use a synonym. For example: "Learn about elastic database pools for multi-tenant databases." In this case multi-tenant database is the industry-standard term that will be an anchor for finding the topic.
62-
6312
-------------------->
64-
6513
# Deploy an ASP.NET web app to Azure App Service by using Visual Studio #
6614

67-
<!------------------
68-
GUIDELINES for introduction
69-
70-
The introduction is 1-2 sentences. It is optimized for search and sets proper expectations about what to expect in the article. It should contain the top keywords that you are using throughout the article.The introduction should be brief and to the point of what users will do and what they will accomplish.
71-
72-
In this example:
73-
74-
75-
Sentence #1 Explains what the user will do. This is also the metadata description.
76-
This tutorial shows how to deploy an ASP.NET web application to a web app in Azure App Service by using Visual Studio 2015.
7715

78-
Sentence #2 Explains what users will learn and the benefit.
79-
When you’re finished, you’ll have a simple web application up and running in the cloud.
16+
<!-----------------
17+
GUIDELINES for Introduction
18+
1-2 sentences: what users will do and what they will accomplish. Again, use strong keywords.
8019

8120
-------------------->
82-
83-
8421
This tutorial shows how to deploy an ASP.NET web application to a [web app in Azure App Service](app-service-web-overview.md) by using Visual Studio 2015. When you’re finished, you’ll have a simple web application up and running in the cloud.
8522

8623

87-
**Time estimate**: This tutorial will take about 10-15 minutes to complete. Installing the Azure SDK for .NET will take additional time: several minutes to a half hour, depending on how many SDK dependencies you have on your computer.
24+
<!------------------
25+
GUIDELINES for time estimate and diagram
26+
Give a time estimate with any useful details. Diagrams are optional but help users see the big picture of what they will do. An optional video of the steps can be used by customers as an alternative to following the steps in the topic. The video doesn't have to be professional.
8827

28+
-------------------->
29+
**Time estimate**: This tutorial will take about 10-15 minutes to complete. Installing the Azure SDK for .NET will take additional time: several minutes to a half hour, depending on how many SDK dependencies you have on your computer.
8930

9031
The diagram illustrates what you do in the tutorial.
9132

9233
![Visual Studio create and deploy diagram](./media/web-sites-dotnet-get-started/Create_App.png)
9334

9435

36+
<!------------------
37+
GUIDELINES for prerequisites
38+
Include getting started info like setting up an account. List technical expertise and software required. Can also add links to conceptual info.
39+
40+
-------------------->
9541
## Prerequisites
9642

9743
* The tutorial assumes you have worked with ASP.NET MVC and Visual Studio. If you need an introduction, see [Getting Started with ASP.NET MVC 5](http://www.asp.net/mvc/overview/getting-started/introduction/getting-started).
@@ -101,29 +47,26 @@ The diagram illustrates what you do in the tutorial.
10147
If you want to get started with Azure App Service before you sign up for an Azure account, go to [Try App Service](http://go.microsoft.com/fwlink/?LinkId=523751). There you can create a short-lived starter app in App Service — no credit card required, and no commitments.
10248

10349

104-
<!--**Procedure**: *This is the first “step”. Make titles H2’s and short and clear – H2’s appear in the right pane on the web page and are important for navigation.*-->
105-
106-
## <a name="setupdevenv"></a>Set up the development environment
107-
108-
The tutorial is written for Visual Studio 2015 with the [Azure SDK for .NET](../dotnet-sdk.md) 2.9 or later.
109-
110-
* [Download the latest Azure SDK for Visual Studio 2015](http://go.microsoft.com/fwlink/?linkid=518003). The SDK installs Visual Studio 2015 if you don't already have it.
50+
<!------------------
51+
GUIDELINES for procedures (steps)
52+
Format headings as H2’s and make them short and clear – H2’s appear in the right pane on the web page and are important for navigation. Usually begin with a verb: configure, download, etc. to let users know they are doing something. Keep number of steps under 10.
11153

54+
Screenshots: Really help users understand where they are. Don’t include too many since they’re difficult to maintain. Highlight areas you are referring to in red.
11255

113-
<!--**Notes**: *Notes provide just-in-time info: A Note is “by the way” info, an Important is info users need to complete a task, Tip is for shortcuts. Don’t overdo*.-->
56+
Next steps: At the end of the procedures give users relevant next steps so they want to go on.
11457

115-
>[AZURE.NOTE] Depending on how many of the SDK dependencies you already have on your machine, installing the SDK could take a long time, from several minutes to a half hour or more.
58+
End of annotations!
11659

117-
If you have Visual Studio 2013 and prefer to use that, you can [download the latest Azure SDK for Visual Studio 2013](http://go.microsoft.com/fwlink/?LinkID=324322). Some screens may look different from the illustrations.
60+
-------------------->
11861

62+
## <a name="setupdevenv"></a>Set up the development environment
11963

120-
<!--**Procedures**: *This is the second “step." They often include substeps. Again, use a short title that tells users what they’ll do*. *("Configure a new web project.")*-->
64+
The tutorial is written for Visual Studio 2015 with the [Azure SDK for .NET](../dotnet-sdk.md) 2.9 or later.
12165

122-
<!--**UI**: *Note the format for documenting the UI: bold for UI elements and arrow keys for sequence. (Ex. Click **File > New > Project**.)*-->
66+
* [Download the latest Azure SDK for Visual Studio 2015](http://go.microsoft.com/fwlink/?linkid=518003). The SDK installs Visual Studio 2015 if you don't already have it.
12367

124-
<!--**Screenshot**: *Screenshots really help users. But don’t include too many since they’re difficult to maintain. Highlight areas you are referring to in red.*-->
12568

126-
<!--**No. of steps**: *Make sure the number of steps within a procedure is 10 or fewer. Seven steps is ideal. Break up long procedure logically.*-->
69+
If you have Visual Studio 2013 and prefer to use that, you can [download the latest Azure SDK for Visual Studio 2013](http://go.microsoft.com/fwlink/?LinkID=324322). Some screens may look different from the illustrations.
12770

12871
## Configure a new web project
12972

‎contributor-guide/templates/tutorial-template.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
---
2+
<!------------------
3+
4+
This is an outline of a tutorial that has high CSAT (https://docs.microsoft.com/en-us/azure/app-service-web/web-sites-dotnet-get-started).
5+
6+
Tutorials show users how to solve a problem. They include prerequisites and steps. They are not "learn concepts" topics.
7+
8+
9+
GUIDELINES for H1
10+
The H1 is the top heading in the article. It tells users what they will do. Use strong keywords: deploy, ASP.NET, web app, App Service, Visual Studio, as you see below.
11+
12+
-------------------->
13+
# Add H1 (top heading) #
14+
15+
16+
<!-----------------
17+
GUIDELINES for Introduction
18+
1-2 sentences: what users will do and what they will accomplish. Again, use strong keywords.
19+
20+
-------------------->
21+
Add introduction
22+
23+
24+
<!------------------
25+
GUIDELINES for time estimate and diagram
26+
Give a time estimate with any useful details. Diagrams are optional but help users see the big picture of what they will do. An optional video of the steps can be used by customers as an alternative to following the steps in the topic. The video doesn't have to be professional.
27+
28+
-------------------->
29+
Add time estimate and optional diagram and/or video.
30+
31+
32+
<!------------------
33+
GUIDELINES for prerequisites
34+
Include getting started info like setting up an account. List technical expertise and software required. Can also add links to conceptual info.
35+
36+
-------------------->
37+
## Prerequisites (H2)
38+
39+
Add prerequisite info.
40+
41+
42+
<!------------------
43+
GUIDELINES for procedures (steps)
44+
Format headings as H2’s and make them short and clear – H2’s appear in the right pane on the web page and are important for navigation. Usually begin with a verb: configure, download, etc. to let users know they are doing something. Keep number of steps under 10.
45+
46+
Screenshots: Really help users understand where they are. Don’t include too many since they’re difficult to maintain. Highlight areas you are referring to in red.
47+
48+
Next steps: At the end of the procedures give users relevant next steps so they want to go on.
49+
50+
End of annotations!
51+
52+
-------------------->
53+
54+
## Procedure title (H2)
55+
56+
Add procedures and include screenshots where helpful.
57+
58+
## Next steps (H2)
59+
60+

0 commit comments

Comments
 (0)