Add topic types

doc/development/documentation/index.md

@@ -12,7 +12,7 @@ The GitLab documentation is [intended as the single source of truth (SSOT)](http
 In addition to this page, the following resources can help you craft and contribute to documentation:
 
 - [Style Guide](styleguide/index.md) - What belongs in the docs, language guidelines, Markdown standards to follow, links, and more.
-- [Structure and template](structure.md) - Learn the typical parts of a doc page and how to write each one.
+- [Topic type template](structure.md) - Learn about the different types of topics.
 - [Documentation process](workflow.md).
 - [Markdown Guide](../../user/markdown.md) - A reference for all Markdown syntax supported by GitLab.
 - [Site architecture](site_architecture/index.md) - How <https://docs.gitlab.com> is built.

doc/development/documentation/structure.md

@@ -5,167 +5,165 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 description: What to include in GitLab documentation pages.
 ---
 
-# Documentation structure and template
+# Documentation topic types
 
-Use these standards to contribute content to the GitLab documentation.
+At GitLab, we have not traditionally used topic types. However, we are starting to
+move in this direction, and we now use four topic types:
 
-Before getting started, familiarize yourself with [Documentation guidelines for GitLab](index.md)
-and the [Documentation Style Guide](styleguide/index.md).
+- [Concept](#concept)
+- [Task](#task)
+- [Reference](#reference)
+- [Troubleshooting](#troubleshooting)
 
-## Components of a documentation page
+Each page contains multiple topic types. For example,
+a page with the title `Pipelines`, which is generated from a file called `index.md`,
+can include a concept and multiple task and reference topics.
 
-Most pages are dedicated to a specific GitLab feature or to a use case that
-involves one or more features, potentially in conjunction with third-party tools.
+GitLab also uses high-level landing pages.
 
-In general, each topic should include the following content, in this sequence:
+## Landing pages
 
-- *Metadata*: Information about the stage, group, and how to find the technical
-  writer for the topic. This information isn't visible in the published help.
-- *Title*: A top-level heading with the feature or use case name. Choose a term
-  that defines the functionality and use the same term in all the resources
-  where the feature is mentioned.
-- *Introduction*: In a few sentences beneath the title, describe what the
-  feature or topic is, what it does, and in what context it should be used.
-- *Use cases*: Describe real user scenarios.
-- *Prerequisites*: Describe the software, configuration, account, permissions,
-  or knowledge required to use this functionality.
-- *Tasks*: Present detailed step-by-step instructions on how to use the feature.
-- *Troubleshooting*: List errors and how to address them. Recommended but not
-  required.
+Landing pages are topics that group other topics and help a user to navigate a section.
 
-You can include additional subsections, as appropriate, such as *How it Works*,
-or *Architecture*. You can also include other logical divisions, such as
-pre-deployment and post-deployment tasks.
+Users who are using the in-product help do not have a left nav,
+and need these topics to navigate the documentation.
 
-## Template for new docs
+These topics can also help other users find the most important topics
+in a section.
 
-Follow the [folder structure and filename guidelines](styleguide/index.md#folder-structure-overview)
-and create a new topic by using this template:
+Landing page topics should be in this format:
 
 ```markdown
-<!--Follow the Style Guide when working on this document.
-https://docs.gitlab.com/ee/development/documentation/styleguide.html
-When done, remove all of this commented-out text, except a commented-out
-Troubleshooting section, which, if empty, can be left in place to encourage future use.-->
----
-description: "Short document description." # Up to ~200 chars long. This information is displayed
-in Google Search snippets. It may help to write the page intro first, and then reuse it here.
-stage: Add the stage name here
-group: Add the group name here
-info: To determine the technical writer assigned to the Stage/Group associated with this page,
-see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
----
+# Title (a noun, like "CI/CD or "Analytics")
 
-# Feature or Use Case Name **[TIER]** (1)
-<!--If you are writing about a use case, start with a verb,
-for example, "Configure", "Implement", + the goal/scenario-->
+Brief introduction to the concept or product area.
+Include the reason why someone would use this thing.
+
+- Bulleted list of important related topics.
+- These links are needed because users of in-product help do not have left navigation.
+```
 
-<!--For pages on newly-introduced features, add the following line.
-If only some aspects of the feature have been introduced, specify which parts of the feature.-->
-> [Introduced](link_to_issue_or_mr) in GitLab (Tier) X.Y (2).
+## Concept
 
-Write a description of the feature or use case. This introduction should answer
-these questions:
+A concept topic introduces a single feature or concept.
 
-- What is this feature or use case?
-- Who is it for?
-- What is the context in which it is used and are there any prerequisites or
-  requirements?
-- What can the audience do with this? (Be sure to consider all applicable
-  audiences, such as GitLab admin and developer-user.)
-- What are the benefits of using this over any existing alternatives?
+A concept should answer the questions:
 
-You can reuse this content, or part of it, for the front matter's `description`
-at the top of this file.
+- What is this?
+- Why would I use it?
 
-## Use cases
+Think of everything someone might want to know if they’ve never heard of this topic before.
 
-Describe common use cases, typically in bulleted form. Include real-life examples
-for each.
+Don’t tell them **how** to do this thing. Tell them **what it is**.
 
-If the page itself is dedicated to a use case, this section usually includes more
-specific scenarios for use (for example, variations on the main use case), but if
-that's not applicable, you can omit this section.
+If you start describing another topic, start a new concept and link to it.
+
+Concept topics should be in this format:
+
+```markdown
+# Title (a noun, like "Widgets")
 
-Examples of use cases on feature pages:
+A paragraph that explains what this thing is.
 
-- CE and EE: [Issues](../../user/project/issues/index.md#use-cases)
-- CE and EE: [Merge Requests](../../user/project/merge_requests/index.md)
-- EE-only: [Geo](../../administration/geo/index.md)
-- EE-only: [Jenkins integration](../../integration/jenkins.md)
+Another paragraph that explains what this thing is.
 
-## Prerequisites
+Remember, if you start to describe about another concept, stop yourself.
+Each concept topic should be about one concept only.
+```
 
-State any prerequisites for using the feature. These might include:
+## Task
 
-- Technical prereqs (for example, an account on a third-party service, an amount
-  of storage space, or prior configuration of another feature)
-- Prerequisite knowledge (for example, familiarity with certain GitLab features
-  or other products and technologies).
+A task topic gives instructions for how to complete a procedure.
 
-Link each one to an appropriate place for more information.
+Task topics should be in this format:
 
-## Tasks
+```markdown
+# Title (starts with an active verb, like "Create a widget" or "Delete a widget")
 
-Each topic should help users accomplish a specific task.
+Do this task when you want to...
 
-The heading should:
+Prerequisites (optional):
 
-- Describe the task and start with a verb. For example, `Create a package` or
-  `Configure a pipeline`.
-- Be short and descriptive (up to ~50 chars).
-- Start from an `h2` (`##`), then go over `h3`, `h4`, `h5`, and `h6` as needed.
-  Never skip a hierarchy level (like `h2` > `h4`). It breaks the table of
-  contents and can affect the breadcrumbs.
+- Thing 1
+- Thing 2
+- Thing 3
 
-Bigger tasks can have subsections that explain specific phases of the process.
+To do this task:
 
-Include example code or configurations when needed. Use Markdown to wrap code
-blocks with [syntax highlighting](../../user/markdown.md#colored-code-and-syntax-highlighting).
+1. Location then action. (Go to this menu, then select this item.)
+1. Another step.
+1. Another step.
 
-Example topic:
+Task result (optional). Next steps (optional).
+```
 
-## Create a teddy bear
+Here is an example.
 
-Create a teddy bear when you need something to hug. (Include the reason why you
-might do the task.)
+```markdown
+# Create an issue
 
-To create a teddy bear:
+Create an issue when you want to track bugs or future work.
 
-1. Go to **Settings > CI/CD**.
-1. Expand **This** and click **This**.
-1. Do another step.
+Prerequisites:
 
-The teddy bear is now in the kitchen, in the cupboard above the sink. _(This is the result.)_
+- A minimum of Contributor access to a project in GitLab.
 
-You can retrieve the teddy bear and put it on the couch with the other animals. _(These are next steps.)_
+To create an issue:
 
-Screenshots are not necessary. They are difficult to keep up-to-date and can
-clutter the page.
+1. Go to **Issues > List**.
+1. In the top right, click **New issue**.
+1. Complete the fields. (If you have a reference topic that lists each field, link to it here.)
+1. Click **Submit issue**.
 
-<!-- ## Troubleshooting
+The issue is created. You can view it by going to **Issues > List**.
+```
 
-Include any troubleshooting steps that you can foresee. If you know beforehand
-what issues one might have when setting this up, or when something is changed,
-or on upgrading, it's important to describe those, too. Think of things that may
-go wrong and include them here. This is important to minimize requests for
-Support, and to avoid documentation comments with questions that you know
-someone might ask.
+## Reference
 
-Each scenario can be a third-level heading, for example, `### Getting error message X`.
-If you have none to add when creating a doc, leave this section in place but
-commented out to help encourage others to add to it in the future. -->
+A reference topic provides information in an easily-scannable format,
+like a table or list. It's similar to a dictionary or encyclopedia entry.
 
----
+```markdown
+# Title (a noun, like "Pipeline settings" or "Administrator options")
 
-Notes:
+Introductory sentence.
 
-- (1): Apply the [tier badges](styleguide/index.md#product-badges) accordingly.
-- (2): Apply the correct format for the
-       [GitLab version that introduces the feature](styleguide/index.md#gitlab-versions-and-tiers).
+| Setting | Description |
+|---------|-------------|
+| **Name** | Descriptive sentence about the setting. |
 ```
 
-## Help and feedback section
+## Troubleshooting
+
+Troubleshooting topics can be one of two categories:
+
+- **Troubleshooting task.** This topic is written the same as a [standard task topic](#task).
+  For example, "Run debug tools" or "Verify syntax."
+- **Troubleshooting reference.** This topic has a specific format.
+
+Troubleshooting reference topics should be in this format:
+
+```markdown
+# Title (the error message or a description of it)
+
+You might get an error that states <error message>.
+
+This issue occurs when...
+
+The workaround is...
+```
+
+## Other information on a topic
+
+Topics include other information.
+
+For example:
+
+- Each topic must have a [tier badge](styleguide/index.md#product-tier-badges).
+- New topics must have information about the
+  [GitLab version where the feature was introduced](styleguide/index.md#where-to-put-version-text).
+
+### Help and feedback section
 
 This section ([introduced](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/319) in GitLab 11.4)
 is displayed at the end of each document and can be omitted by adding a key into
@@ -180,7 +178,7 @@ feedback: false
 The default is to leave it there. If you want to omit it from a document, you
 must check with a technical writer before doing so.
 
-### Disqus
+#### Disqus
 
 We also have integrated the docs site with Disqus (introduced by
 [!151](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/151)),
@@ -206,7 +204,7 @@ The click events in the feedback section are tracked with Google Tag Manager.
 The conversions can be viewed on Google Analytics by navigating to
 **Behavior > Events > Top events > docs**.
 
-## Guidelines for good practices
+### Guidelines for good practices
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36576/) in GitLab 13.2 as GitLab Development documentation.
 

doc/development/documentation/styleguide/index.md

@@ -15,9 +15,7 @@ For guidelines specific to text in the GitLab interface, see the Pajamas [Conten
 
 For information on how to validate styles locally or by using GitLab CI/CD, see [Testing](../testing.md).
 
-Use this guide for standards on grammar, formatting, word usage, and more.
-
-You can also view a list of [recent updates to this guide](https://gitlab.com/dashboard/merge_requests?scope=all&utf8=%E2%9C%93&state=merged&label_name[]=tw-style&not[label_name][]=docs%3A%3Afix).
+You can view a list of [recent updates to this guide](https://gitlab.com/dashboard/merge_requests?scope=all&utf8=%E2%9C%93&state=merged&label_name[]=tw-style&not[label_name][]=docs%3A%3Afix).
 
 If you can't find what you need:
 
@@ -31,10 +29,8 @@ If you have questions about style, mention `@tw-style` in an issue or merge requ
 
 ## Documentation is the single source of truth (SSOT)
 
-### Why a single source of truth
-
-The documentation of GitLab products and features is the SSOT for all
-information related to implementation, usage, and troubleshooting. It evolves
+The GitLab documentation is the SSOT for all
+information related to GitLab implementation, usage, and troubleshooting. It evolves
 continuously, in keeping with new products and features, and with improvements
 for clarity, accuracy, and completeness.
 
@@ -44,7 +40,7 @@ about GitLab products.
 It also informs decisions about the kinds of content we include in our
 documentation.
 
-### All information
+### The documentation includes all information
 
 Include problem-solving actions that may address rare cases or be considered
 _risky_, but provide proper context through fully-detailed
@@ -54,10 +50,13 @@ If you think you have found an exception to this rule, contact the
 Technical Writing team.
 
 GitLab adds all troubleshooting information to the documentation, no matter how
-unlikely a user is to encounter a situation. For the [Troubleshooting sections](#troubleshooting),
-people in GitLab Support can merge additions themselves.
+unlikely a user is to encounter a situation.
 
-### All media types
+GitLab Support maintains their own
+[troubleshooting content](../../../administration/index.md#support-team-docs)
+in the GitLab documentation.
+
+### The documentation includes all media types
 
 Include any media types/sources if the content is relevant to readers. You can
 freely include or link presentations, diagrams, and videos. No matter who
@@ -71,48 +70,33 @@ include it.
   quotation with the source cited. Typically it is better to either rephrase
   relevant information in your own words or link out to the other source.
 
-### No special types
+### Topic types
 
 In the software industry, it is a best practice to organize documentation in
-different types. For example, [Divio recommends](https://www.divio.com/blog/documentation/):
-
-- Tutorials
-- How-to guides
-- Explanation
-- Reference (for example, a glossary)
-
-At GitLab, we have so many product changes in our monthly releases that we can't
-afford to continuously update multiple types of information. If we have multiple
-types, the information becomes outdated. Therefore, we have a
-[single template](../structure.md) for documentation.
-
-GitLab documentation does not distinguish specific document types. We are open to
-reconsidering this policy after the documentation has reached a future stage of
-maturity and quality. If you are reading this, then despite our continuous
-improvement efforts, that point hasn't been reached.
-
-### Link instead of summarize
+different types. For example:
 
-There is a temptation to summarize the information on another page, which
-causes the information to live in two places. Instead, link to the single source
-of truth and explain why it is important to consume the information.
+- Concepts
+- Tasks
+- Reference
+- Troubleshooting
 
-### Organize by topic, not by type
+At GitLab, we have not traditionally used topic types. However, we are starting to
+move in this direction, so we can address these issues:
 
-We organize content by topic, not by type, so it can be located in the
-single-source-of-truth (SSOT) section for the subject matter. Top-level audience-type
-folders, like `administration`, are exceptions.
+- **Content is hard to find.** Our docs are comprehensive and include a large amount of
+  useful information. Topic types create repeatable patterns that make our content easier
+  to scan and parse.
+- **Content is often written from the contributor's point of view.**  Our docs
+  are written by contributors. Topic types (tasks specifically) help put
+  information into a format that is geared toward helping others, rather than
+  documenting how a feature was implemented.
 
-For example, do not create groupings of similar media types. For example:
+GitLab uses these [topic type templates](../structure.md).
 
-- Glossaries.
-- FAQs.
-- Sets of all articles or videos.
+### Link instead of repeating text
 
-Such grouping of content by type makes it difficult to browse for the information
-you need and difficult to maintain up-to-date content. Instead, organize content
-by its subject (for example, everything related to CI goes together) and
-cross-link between any related content.
+Rather than repeating information from another topic, link to the single source
+of truth and explain why it is important.
 
 ### Docs-first methodology
 
@@ -127,14 +111,9 @@ of GitLab more efficient.
   should be to create a merge request (MR) to add this information to the
   documentation. You can then share the MR to communicate this information.
 
-New information about the future usage or troubleshooting
-of GitLab should not be written directly in a forum or other messaging system.
-Instead, add it to a documentation merge request, then reference it. Note
-that among any other documentation changes, you can either:
-
-- Add a [Troubleshooting section](#troubleshooting) to a doc if none exists.
-- Un-comment and use the placeholder Troubleshooting section included as part of
-  our [documentation template](../structure.md#template-for-new-docs), if present.
+New information that would be useful toward the future usage or troubleshooting
+of GitLab should not be written directly in a forum or other messaging system,
+but added to a documentation MR and then referenced, as described above. 
 
 The more we reflexively add information to the documentation, the more
 the documentation helps others efficiently accomplish tasks and solve problems.
@@ -217,8 +196,11 @@ included in backticks. For example:
 
 ## Structure
 
-Because we want documentation to be a SSOT, we should [organize by topic, not by
-type](#organize-by-topic-not-by-type).
+We include concept and task topic types in the same larger topic.
+
+In general, we have one topic that's a [landing page](../structure.md#landing-pages).
+Below that topic in the left nav are individual topics. Each of these include a concept
+and multiple related tasks, reference, and troubleshooting topics.
 
 ### Folder structure overview
 
@@ -299,7 +281,7 @@ place for it.
 ### Avoid duplication
 
 Do not include the same information in multiple places.
-[Link to a single source of truth instead.](#link-instead-of-summarize)
+[Link to a single source of truth instead.](#link-instead-of-repeating-text)
 
 ### References across documents
 
@@ -966,8 +948,8 @@ this option.
 
 ## Links
 
-Links are important in GitLab documentation. They allow you to [link instead of
-summarizing](#link-instead-of-summarize) to help preserve a [single source of truth](#why-a-single-source-of-truth)
+Links are important in GitLab documentation. Use links instead of
+summarizing to help preserve a [single source of truth](#documentation-is-the-single-source-of-truth-ssot)
 in GitLab documentation.
 
 We include guidance for links in these categories:
@@ -1895,21 +1877,6 @@ In this case:
 - Use the [GitLab Restart](#gitlab-restart) section to explain any required
   restart or reconfigure of GitLab.
 
-### Troubleshooting
-
-For troubleshooting sections, provide as much context as possible so
-users can identify their problem and resolve it on their own. You
-can facilitate this by making sure the troubleshooting content addresses:
-
-1. The problem the user needs to solve.
-1. How the user can confirm they have the problem.
-1. Steps the user can take towards resolution of the problem.
-
-If the contents of each category can be summarized in one line and a list of
-steps aren't required, consider setting up a [table](#tables). Create headers of
-_Problem_ \| _Cause_ \| _Solution_ (or _Workaround_ if the fix is temporary), or
-_Error message_ \| _Solution_.
-
 ## Feature flags
 
 Learn how to [document features deployed behind flags](../feature_flags.md). For