Add latest changes from gitlab-org/gitlab@master

1 files changed, 29 insertions, 24 deletions

diff --git a/doc/development/documentation/topic_types/index.md b/doc/development/documentation/topic_types/index.md
index 511c8cdb345..37ed876fc59 100644
--- a/doc/development/documentation/topic_types/index.md
+++ b/doc/development/documentation/topic_types/index.md
@@ -16,14 +16,38 @@ Each topic on a page should be one of the following topic types:
 Even if a page is short, the page usually starts with a concept and then
 includes a task or reference topic.
 
-The tech writing team sometimes uses the acronym `CTRT` to refer to our topic types.
+The tech writing team sometimes uses the acronym `CTRT` to refer to the topic types.
 The acronym refers to the first letter of each topic type.
 
-In addition to the four primary topic types, we also have:
+## Other page and topic types
 
-- [Tutorials](tutorial.md) (a page type)
-- [Get started](#get-started) (a page type)
-- [Glossaries](glossary.md) (a topic or page type)
+In addition to the four primary topic types, you can use the following:
+
+- Page types: [Tutorials](tutorial.md) and [Get started](#get-started)
+- Topic type: [Related topics](#related-topics)
+- Page or topic type: [Glossaries](glossary.md)
+
+## Pages and topics to avoid
+
+You should avoid:
+
+- Pages that are exclusively links to other pages. The only exception are
+  top-level pages that aid with navigation.
+- Topics that have one or two sentences only. In these cases:
+  - Incorporate the information in another topic.
+  - If the sentence links to another page, use a [Related topics](#related-topics) link instead.
+
+## Topic title guidelines
+
+In general, for topic titles:
+
+- Be clear and direct. Make every word count.
+- Use articles and prepositions.
+- Follow [capitalization](../styleguide/index.md#capitalization) guidelines.
+- Do not repeat text from earlier topic titles. For example, if the page is about merge requests,
+  instead of `Troubleshooting merge requests`, use only `Troubleshooting`.
+
+See also [guidelines for heading levels in Markdown](../styleguide/index.md#heading-levels-in-markdown).
 
 ## Related topics
 
@@ -63,22 +87,3 @@ 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
-
-Some pages are solely a list of links to other documentation.
-
-We do not encourage this page type. Lists of links can get out-of-date quickly
-and offer little value to users, who prefer to search to find information.
-
-## Topic title guidelines
-
-In general, for topic titles:
-
-- Be clear and direct. Make every word count.
-- Use articles and prepositions.
-- Follow [capitalization](../styleguide/index.md#capitalization) guidelines.
-- Do not repeat text from earlier topic titles. For example, if the page is about merge requests,
-  instead of `Troubleshooting merge requests`, use only `Troubleshooting`.
-
-See also [guidelines for heading levels in Markdown](../styleguide/index.md#heading-levels-in-markdown).