Skip to content

Commit 023b179

Browse files
YaelSchusterYaelSchuster
authored
Create tutorial template for documentation
Added a tutorial template for documentation purposes.
1 parent 06af8ec commit 023b179

File tree

1 file changed

+174
-0
lines changed

1 file changed

+174
-0
lines changed

‎.github/agents/templates/tutorial.md‎

Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
---
2+
title: Page title has the greatest effect on search
3+
description: The meta-description is not crawled for search rank, but is displayed in the browser.
4+
author: <github account>
5+
ms.author: <MS alias>
6+
ms.service: <service-slug>
7+
ms.topic: tutorial
8+
ms.custom: mvc
9+
ms.date: 11/16/2017
10+
11+
---
12+
<!---Recommended: Remove all the comments in this template before you
13+
sign-off or merge to main.--->
14+
15+
<!---Tutorials are scenario-based procedures for the top customer tasks
16+
identified in milestone one of the
17+
[C+E Skilling content model](contribute-get-started-mvc.md).
18+
You only use tutorials to show the single best procedure for completing
19+
an approved top 10 customer task.
20+
--->
21+
22+
# Tutorial: <do something with X>
23+
<!---Required:
24+
Starts with "Tutorial: "
25+
Make the first word following "Tutorial:" a verb.
26+
--->
27+
28+
Introductory paragraph.
29+
<!---Required:
30+
Lead with a light intro that describes, in customer-friendly language,
31+
what the customer will learn, or do, or accomplish. Answer the
32+
fundamental "why would I want to do this?" question.
33+
--->
34+
35+
In this tutorial, you learn how to:
36+
37+
> [!div class="checklist"]
38+
> * All tutorials include a list summarizing the steps to completion
39+
> * Each of these bullet points align to a key H2
40+
> * Use these green checkboxes in a tutorial
41+
<!---Required:
42+
Include the outline of the tutorial in the beginning and at
43+
the end of every tutorial. These will align to the **procedural** H2
44+
headings for the activity. You do not need to include all H2 headings.
45+
Leave out the prerequisites, clean-up resources and next steps--->
46+
47+
If you don't have a <service> subscription, create a free trial account...
48+
<!--- Required, if a free trial account exists.
49+
Because we intend tutorials to help new customers use the product or
50+
service to finish a top task, include a link to a free trial before the
51+
first H2, if one exists. You can find listed examples in
52+
[Write tutorials](contribute-how-to-mvc-tutorial.md)
53+
--->
54+
55+
<!---Avoid notes, tips, and important boxes. Readers tend to skip over
56+
them. Better to put that info directly into the article text.--->
57+
58+
## Prerequisites
59+
60+
- First prerequisite
61+
- Second prerequisite
62+
- Third prerequisite
63+
<!---If you need them, make Prerequisites your first H2 in a tutorial. If
64+
there's something a customer needs to take care of before they start (for
65+
example, creating a VM) it's OK to link to that content before they
66+
begin.--->
67+
68+
## Sign in to <service/product/tool name>
69+
70+
Sign in to the [<service> portal](url).
71+
<!---If you need to sign in to the portal to do the tutorial, the article requires this H2 and
72+
link.--->
73+
74+
## Procedure 1
75+
76+
<!---Required:
77+
Tutorials are prescriptive and guide the customer through an end-to-end
78+
procedure. Make sure to use specific naming for setting up accounts and
79+
configuring technology.
80+
Don't link off to other content - include whatever the customer needs to
81+
finish the scenario in the article. For example, if the customer needs
82+
to set permissions, include the permissions they need to set, and the
83+
specific settings in the tutorial procedure. Don't send the customer to
84+
another article to read about it.
85+
In a break from tradition, do not link to reference topics in the
86+
procedural part of the tutorial when using cmdlets or code. Provide customers
87+
what they need to know in the tutorial to successfully finish
88+
the tutorial.
89+
For portal-based procedures, minimize bullets and numbering.
90+
For the CLI or PowerShell based procedures, don't use bullets or
91+
numbering.
92+
--->
93+
94+
Include a sentence or two to explain only what the reader needs to do to finish the
95+
procedure.
96+
97+
1. Step one of the procedure
98+
1. Step two of the procedure
99+
1. Step three of the procedure
100+
:::image type="content" border="true" source="media/contribute-how-to-mvc-tutorial/browser.png" alt-text="Browser.":::
101+
102+
<!---Use screenshots but be judicious to maintain a reasonable length.
103+
Make sure screenshots align to the
104+
[current standards](https://review.learn.microsoft.com/help/contribute/contribute-how-to-create-screenshot).
105+
If users access your product/service via a web browser the first
106+
screenshot should always include the full browser window in Chrome or
107+
Safari. This is to show users that the portal is browser-based - OS
108+
and browser agnostic.--->
109+
1. Step four of the procedure
110+
111+
## Procedure 2
112+
113+
Include a sentence or two to explain only what the reader needs to do to finish the procedure.
114+
115+
1. Step one of the procedure
116+
1. Step two of the procedure
117+
1. Step three of the procedure
118+
119+
## Procedure 3
120+
121+
Include a sentence or two to explain only what the reader needs to do to finish the
122+
procedure.
123+
<!---Code requires specific formatting. Here are a few useful examples of
124+
commonly used code blocks. Make sure to use the interactive functionality
125+
where possible.
126+
For the CLI or PowerShell based procedures, don't use bullets or
127+
numbering.--->
128+
129+
Here is an example of a code block for Java:
130+
131+
```java
132+
cluster = Cluster.build(new File("src/remote.yaml")).create();
133+
...
134+
client = cluster.connect();
135+
```
136+
137+
or a code block for Azure CLI:
138+
139+
```azurecli-interactive
140+
az vm create --resource-group myResourceGroup --name myVM --image win2016datacenter --admin-username azureuser --admin-password <password>
141+
```
142+
or a code block for Azure PowerShell:
143+
144+
```azurepowershell-interactive
145+
New-AzureRmContainerGroup -ResourceGroupName myResourceGroup -Name mycontainer -Image mcr.microsoft.com/windows/servercore/iis:nanoserver -OsType Windows -IpAddressType Public
146+
```
147+
148+
## Clean up resources
149+
150+
If you're not going to continue to use this application, delete
151+
<resources> with the following steps:
152+
153+
1. From the left-hand menu...
154+
2. ...click Delete, enter...and then click Delete
155+
156+
<!---Required:
157+
To avoid any costs associated with following the tutorial procedure, a
158+
Clean up resources (H2) should come just before Next steps (H2)
159+
--->
160+
161+
## Next steps
162+
163+
Advance to the next article to learn how to create...
164+
> [!div class="nextstepaction"]
165+
> [Next steps button](contribute-get-started-mvc.md)
166+
167+
<!--- Required:
168+
Tutorials should always have a Next steps H2 that points to the next
169+
logical tutorial in a series, or, if there are no other tutorials, to
170+
some other cool thing the customer can do. A single link in the blue box
171+
format should direct the customer to the next article - and you can
172+
shorten the title in the boxes if the original one doesn't fit.
173+
Do not use a "More info section" or a "Resources section" or a "See also
174+
section". --->

0 commit comments

Comments
 (0)