Add latest changes from gitlab-org/gitlab@master

2 files changed, 84 insertions, 56 deletions

diff --git a/doc/development/documentation/topic_types/index.md b/doc/development/documentation/topic_types/index.md
index 8403fd26517..d88a5448d53 100644
--- a/doc/development/documentation/topic_types/index.md
+++ b/doc/development/documentation/topic_types/index.md
@@ -20,11 +20,10 @@ The acronym refers to the first letter of each topic type.
 In general, each page in the GitLab documentation contains multiple topics.
 Each topic on a page should be recognizable as a specific topic type.
 
-## Other topic types
+In addition to the four primary topic types, we also have a page type for
+[Tutorials](tutorial.md) and [Get started](#get-started).
 
-In addition to the four primary topic types, we have a few other types.
-
-### Related topics
+## Related topics
 
 If inline links are not sufficient, you can create a topic called **Related topics**
 and include an unordered list of related topics. This topic should be above the Troubleshooting section.
@@ -36,57 +35,7 @@ and include an unordered list of related topics. This topic should be above the
 - [Trigger a pipeline manually](link-to-topic).
 ```
 
-### Tutorials
-
-A tutorial is page that contains an end-to-end walkthrough of a complex workflow or scenario.
-In general, you might consider using a tutorial when:
-
-- The workflow requires a number of sequential steps where each step consists
-  of sub-steps.
-- The steps cover a variety of GitLab features or third-party tools.
-
-Tutorials are learning aids that complement our core documentation.
-They do not introduce new features.
-Always use the primary [topic types](#documentation-topic-types-ctrt) to document new features.
-
-Tutorials should be in this format:
-
-```markdown
-# Title (starts with "Tutorial:" followed by an active verb, like "Tutorial: Create a website")
-
-A paragraph that explains what the tutorial does, and the expected outcome.
-
-To create a website:
-
-1. [Do the first task](#do-the-first-task)
-1. [Do the second task](#do-the-second-task)
-
-Prerequisites (optional):
-
-- Thing 1
-- Thing 2
-- Thing 3
-
-## Do the first task
-
-To do step 1:
-
-1. First step.
-1. Another step.
-1. Another step.
-
-## Do the second task
-
-Before you begin, make sure you have [done the first task](#do-the-first-task).
-
-To do step 2:
-
-1. First step.
-1. Another step.
-1. Another step.
-```
-
-### Get started
+## Get started
 
 A get started page is a set of steps to help a user get set up
 quickly to use a single GitLab feature or tool.
@@ -110,7 +59,7 @@ consider using subsections for each distinct task.
 In the left nav, use `Get started` as the text. On the page itself, spell out
 the full name. For example, `Get started with application security`.
 
-### Topics and resources
+## Topics and resources
 
 Some pages are solely a list of links to other documentation.
 
diff --git a/doc/development/documentation/topic_types/tutorial.md b/doc/development/documentation/topic_types/tutorial.md
new file mode 100644
index 00000000000..0164b525528
--- /dev/null
+++ b/doc/development/documentation/topic_types/tutorial.md
@@ -0,0 +1,79 @@
+---
+stage: none
+group: Style Guide
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
+---
+
+# Tutorial topic type
+
+A tutorial is page that contains an end-to-end walkthrough of a complex workflow or scenario.
+In general, you might consider using a tutorial when:
+
+- The workflow requires a number of sequential steps where each step consists
+  of sub-steps.
+- The steps cover a variety of GitLab features or third-party tools.
+
+Tutorials are learning aids that complement our core documentation.
+They do not introduce new features.
+Always use the primary [topic types](index.md) to document new features.
+
+Tutorials should be in this format:
+
+```markdown
+# Title (starts with "Tutorial:" followed by an active verb, like "Tutorial: Create a website")
+
+A paragraph that explains what the tutorial does, and the expected outcome.
+
+To create a website:
+
+1. [Do the first task](#do-the-first-task)
+1. [Do the second task](#do-the-second-task)
+
+Prerequisites (optional):
+
+- Thing 1
+- Thing 2
+- Thing 3
+
+## Do the first task
+
+To do step 1:
+
+1. First step.
+1. Another step.
+1. Another step.
+
+## Do the second task
+
+Before you begin, make sure you have [done the first task](#do-the-first-task).
+
+To do step 2:
+
+1. First step.
+1. Another step.
+1. Another step.
+```
+
+## Tutorial headings
+
+Start with `Tutorial:` followed by an active verb, like `Tutorial: Create a website`.
+
+## Screenshots
+
+You can include screenshots in a tutorial to illustrate important steps in the process.
+In the core product documentation, you should [use screenshots sparingly](../styleguide/index.md#images).
+However, in tutorials, screenshots can help users understand where they are in a complex process.
+
+Try to balance the number of screenshots in the tutorial so they don't disrupt
+the narrative flow. For example, do not put one large screenshot in the middle of the tutorial.
+Instead, put multiple, smaller screenshots throughout.
+
+## Tutorial voice
+
+Use a friendlier tone than you would for other topic types. For example,
+you can:
+
+- Add encouraging or congratulatory phrases after tasks.
+- Use future tense from time to time, especially when you're introducing
+  steps. For example, `Next, you will associate your issues with your epics`.
+- Be more conversational. For example, `This task might take a while to complete`.