diff options
Diffstat (limited to 'doc/development/documentation/structure.md')
| -rw-r--r-- | doc/development/documentation/structure.md | 204 |
1 files changed, 142 insertions, 62 deletions
diff --git a/doc/development/documentation/structure.md b/doc/development/documentation/structure.md index 871fb26ce08..ac934673ee2 100644 --- a/doc/development/documentation/structure.md +++ b/doc/development/documentation/structure.md @@ -7,61 +7,40 @@ description: What to include in GitLab documentation pages. # Documentation topic types -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: +At GitLab, we have not traditionally used types for our content. However, we are starting to +move in this direction, and we now use four primary topic types: - [Concept](#concept) - [Task](#task) - [Reference](#reference) - [Troubleshooting](#troubleshooting) -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. +In general, each page in our docset contains multiple topics. (Each heading indicates a new topic.) +Each topic on a page should be a specific topic type. For example, +a page with the title `Pipelines` can include topics that are concepts and tasks. -GitLab also uses high-level landing pages. - -## Landing pages - -Landing pages are topics that group other topics and help a user to navigate a section. - -Users who are using the in-product help do not have a left nav, -and need these topics to navigate the documentation. - -These topics can also help other users find the most important topics -in a section. - -Landing page topics should be in this format: - -```markdown -# Title (a noun, like "CI/CD or "Analytics") - -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. -``` +A page might also contain only one type of information. These pages are generally one of our +[other content types](#other-types-of-content). ## Concept -A concept topic introduces a single feature or concept. +A concept introduces a single feature or concept. A concept should answer the questions: - What is this? - Why would I use it? -Think of everything someone might want to know if they've never heard of this topic before. +Think of everything someone might want to know if they've never heard of this concept before. Don't tell them **how** to do this thing. Tell them **what it is**. -If you start describing another topic, start a new concept and link to it. +If you start describing another concept, start a new concept and link to it. -Also, do not use "Overview" or "Introduction" for the topic title. Instead, +Also, do not use **Overview** or **Introduction** for the title. Instead, use a noun or phrase that someone would search for. -Concept topics should be in this format: +Concepts should be in this format: ```markdown # Title (a noun, like "Widgets") @@ -71,14 +50,14 @@ A paragraph that explains what this thing is. Another paragraph that explains what this thing is. Remember, if you start to describe about another concept, stop yourself. -Each concept topic should be about one concept only. +Each concept should be about one concept only. ``` ## Task -A task topic gives instructions for how to complete a procedure. +A task gives instructions for how to complete a procedure. -Task topics should be in this format: +Tasks should be in this format: ```markdown # Title (starts with an active verb, like "Create a widget" or "Delete a widget") @@ -113,20 +92,21 @@ Prerequisites: To create an issue: -1. Go to **Issues > List**. -1. In the top right, select **New issue**. -1. Complete the fields. (If you have a reference topic that lists each field, link to it here.) +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Issues > List**. +1. In the top right corner, select **New issue**. +1. Complete the fields. (If you have reference content that lists each field, link to it here.) 1. Select **Create issue**. The issue is created. You can view it by going to **Issues > List**. ``` -If you have several tasks on a page that share prerequisites, you can make a -reference topic with the title **Prerequisites**, and link to it. +If you have several tasks on a page that share prerequisites, you can use the title +**Prerequisites**, and link to it. ## Reference -A reference topic provides information in an easily-scannable format, +Reference information should be in an easily-scannable format, like a table or list. It's similar to a dictionary or encyclopedia entry. ```markdown @@ -139,18 +119,18 @@ Introductory sentence. | **Name** | Descriptive sentence about the setting. | ``` -If a feature or concept has its own prerequisites, you can use the reference -topic type to create a **Prerequisites** header for the information. +If a feature or concept has its own prerequisites, you can use reference +content to create a **Prerequisites** header for the information. ## Troubleshooting -Troubleshooting topics can be one of two categories: +Troubleshooting can be one of two categories: -- **Troubleshooting task.** This topic is written the same as a [standard task topic](#task). +- **Troubleshooting task.** This information is written the same way as a [standard task](#task). For example, "Run debug tools" or "Verify syntax." -- **Troubleshooting reference.** This topic has a specific format. +- **Troubleshooting reference.** This information has a specific format. -Troubleshooting reference topics should be in this format: +Troubleshooting reference information should be in this format: ```markdown # Title (the error message or a description of it) @@ -162,25 +142,125 @@ This issue occurs when... The workaround is... ``` -For the topic title: +For the heading: -- Consider including at least a partial error message in the title. +- Consider including at least a partial error message. - Use fewer than 70 characters. -Remember to include the complete error message in the topics content if it is -not complete in the title. +If you do not put the full error in the title, include it in the body text. + +## Other types of content + +There are other types of content in the GitLab documentation that don't +classify as one of the four primary [topic types](#documentation-topic-types). +These include: + +- [Tutorials](#tutorials) +- [Get started pages](#get-started) +- [Topics and resources pages](#topics-and-resources-pages) + +In most cases, these pages are standalone. + +### Tutorials + +A tutorial is 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) 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: + +- [Step 1: Do the first task](#do-the-first-task) +- [Step 2: 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. +2. Another step. +3. 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. +2. Another step. +3. Another step. +``` + +### 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. +It might consist of more than one task. + +Get started pages should be in this format: + +```markdown +# Title ("Get started with <feature>") + +Complete the following steps to ... . + +1. First step. +1. Another step. +1. Another step. + +If you need to add more than one task, +consider using subsections for each distinct task. +``` -## Other information on a topic +### Topics and resources pages -Topics include other information. +This is a page with a list of links that point to important sections +of documentation for a specific GitLab feature or tool. -For example: +We do not encourage the use of these types of pages. +Lists like this can get out of date quickly and offer little value to users. +We've included this type here because: -- 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). +- There are existing pages in the documentation that follow this format, + and they should be standardized. +- They can sometimes help navigate a complex section of the documentation. + +If you come across a page like this +or you have to create one, use this format: + +```markdown +# Title ("Topics and resources for <feature>") + +Brief sentence to describe the feature. + +Refer to these resources for more information about <this feature>: + +- Link 1 +- Link 2 +- Link 3 +``` -### Help and feedback section +## 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 @@ -195,7 +275,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)), @@ -210,7 +290,7 @@ comments: false --- ``` -We're hiding comments only in main index pages, such as [the main documentation index](../../README.md), +We're hiding comments only in main index pages, such as [the main documentation index](../../index.md), since its content is too broad to comment on. Before omitting Disqus, you must check with a technical writer. @@ -221,7 +301,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. |