2018-08-16 09:30:04 +00:00
---
2020-09-14 15:09:28 +00:00
stage: none
group: Style Guide
2020-11-26 06:09:20 +00:00
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
2018-12-31 17:05:12 +00:00
description: What to include in GitLab documentation pages.
2018-08-16 09:30:04 +00:00
---
2021-02-02 00:09:14 +00:00
# Documentation topic types
2018-08-16 09:30:04 +00:00
2021-02-02 00:09:14 +00:00
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:
2018-08-16 09:30:04 +00:00
2021-02-02 00:09:14 +00:00
- [Concept ](#concept )
- [Task ](#task )
- [Reference ](#reference )
- [Troubleshooting ](#troubleshooting )
2018-08-16 09:30:04 +00:00
2021-02-02 00:09:14 +00:00
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.
2018-08-16 09:30:04 +00:00
2021-02-02 00:09:14 +00:00
GitLab also uses high-level landing pages.
2020-09-14 15:09:28 +00:00
2021-02-02 00:09:14 +00:00
## Landing pages
2020-09-14 15:09:28 +00:00
2021-02-02 00:09:14 +00:00
Landing pages are topics that group other topics and help a user to navigate a section.
2020-09-14 15:09:28 +00:00
2021-02-02 00:09:14 +00:00
Users who are using the in-product help do not have a left nav,
and need these topics to navigate the documentation.
2018-08-16 09:30:04 +00:00
2021-02-02 00:09:14 +00:00
These topics can also help other users find the most important topics
in a section.
2018-08-16 09:30:04 +00:00
2021-02-02 00:09:14 +00:00
Landing page topics should be in this format:
2018-08-16 09:30:04 +00:00
2020-05-19 18:08:11 +00:00
```markdown
2021-02-02 00:09:14 +00:00
# Title (a noun, like "CI/CD or "Analytics")
2018-08-16 09:30:04 +00:00
2021-02-02 00:09:14 +00:00
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.
```
2018-08-16 09:30:04 +00:00
2021-02-02 00:09:14 +00:00
## Concept
2018-08-16 09:30:04 +00:00
2021-02-02 00:09:14 +00:00
A concept topic introduces a single feature or concept.
2018-08-16 09:30:04 +00:00
2021-02-02 00:09:14 +00:00
A concept should answer the questions:
2020-09-14 15:09:28 +00:00
2021-02-02 00:09:14 +00:00
- What is this?
- Why would I use it?
2018-08-16 09:30:04 +00:00
2021-03-17 15:09:03 +00:00
Think of everything someone might want to know if they've never heard of this topic before.
2018-08-16 09:30:04 +00:00
2021-03-17 15:09:03 +00:00
Don't tell them **how** to do this thing. Tell them **what it is** .
2018-12-31 17:46:12 +00:00
2021-02-02 00:09:14 +00:00
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")
2018-12-31 18:04:46 +00:00
2021-02-02 00:09:14 +00:00
A paragraph that explains what this thing is.
2020-09-14 15:09:28 +00:00
2021-02-02 00:09:14 +00:00
Another paragraph that explains what this thing is.
2018-08-16 09:30:04 +00:00
2021-02-02 00:09:14 +00:00
Remember, if you start to describe about another concept, stop yourself.
Each concept topic should be about one concept only.
```
2018-08-16 09:30:04 +00:00
2021-02-02 00:09:14 +00:00
## Task
2018-12-31 17:46:12 +00:00
2021-02-02 00:09:14 +00:00
A task topic gives instructions for how to complete a procedure.
2018-08-16 09:30:04 +00:00
2021-02-02 00:09:14 +00:00
Task topics should be in this format:
2018-08-16 09:30:04 +00:00
2021-02-02 00:09:14 +00:00
```markdown
# Title (starts with an active verb, like "Create a widget" or "Delete a widget")
2018-08-16 09:30:04 +00:00
2021-02-02 00:09:14 +00:00
Do this task when you want to...
2020-07-23 21:09:19 +00:00
2021-02-02 00:09:14 +00:00
Prerequisites (optional):
2020-09-14 15:09:28 +00:00
2021-02-02 00:09:14 +00:00
- Thing 1
- Thing 2
- Thing 3
2020-07-23 21:09:19 +00:00
2021-02-02 00:09:14 +00:00
To do this task:
2018-08-16 09:30:04 +00:00
2021-02-02 00:09:14 +00:00
1. Location then action. (Go to this menu, then select this item.)
1. Another step.
1. Another step.
2018-08-16 09:30:04 +00:00
2021-02-02 00:09:14 +00:00
Task result (optional). Next steps (optional).
```
2020-08-05 21:09:40 +00:00
2021-02-02 00:09:14 +00:00
Here is an example.
2020-08-05 21:09:40 +00:00
2021-02-02 00:09:14 +00:00
```markdown
# Create an issue
2020-08-05 21:09:40 +00:00
2021-02-02 00:09:14 +00:00
Create an issue when you want to track bugs or future work.
2020-08-05 21:09:40 +00:00
2021-02-02 00:09:14 +00:00
Prerequisites:
2020-08-05 21:09:40 +00:00
2021-02-02 00:09:14 +00:00
- A minimum of Contributor access to a project in GitLab.
2020-08-05 21:09:40 +00:00
2021-02-02 00:09:14 +00:00
To create an issue:
2020-08-05 21:09:40 +00:00
2021-02-02 00:09:14 +00:00
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.)
2021-04-01 12:08:56 +00:00
1. Click **Create issue** .
2020-08-05 21:09:40 +00:00
2021-02-02 00:09:14 +00:00
The issue is created. You can view it by going to **Issues > List** .
```
2018-08-16 09:30:04 +00:00
2021-02-02 00:09:14 +00:00
## Reference
2018-12-31 18:04:46 +00:00
2021-02-02 00:09:14 +00:00
A reference topic provides information in an easily-scannable format,
like a table or list. It's similar to a dictionary or encyclopedia entry.
2018-10-18 11:58:55 +00:00
2021-02-02 00:09:14 +00:00
```markdown
# Title (a noun, like "Pipeline settings" or "Administrator options")
2018-08-16 09:30:04 +00:00
2021-02-02 00:09:14 +00:00
Introductory sentence.
2018-08-16 09:30:04 +00:00
2021-02-02 00:09:14 +00:00
| Setting | Description |
|---------|-------------|
| **Name** | Descriptive sentence about the setting. |
2018-10-18 11:58:55 +00:00
```
2021-02-02 00:09:14 +00:00
## 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...
```
2021-03-29 18:09:37 +00:00
For the topic title:
- Consider including at least a partial error message in the title.
- Use fewer than 70 characters.
Remember to include the complete error message in the topics content if it is
not complete in the title.
2021-02-02 00:09:14 +00:00
## 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
2018-10-18 11:58:55 +00:00
2020-09-14 15:09:28 +00:00
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
the front matter:
2018-10-18 11:58:55 +00:00
```yaml
---
feedback: false
---
```
2020-09-14 15:09:28 +00:00
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.
2018-10-18 11:58:55 +00:00
2021-02-02 00:09:14 +00:00
#### Disqus
2018-10-18 11:58:55 +00:00
We also have integrated the docs site with Disqus (introduced by
2020-02-06 15:09:11 +00:00
[!151 ](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/151 )),
2018-10-18 11:58:55 +00:00
allowing our users to post comments.
2020-09-14 15:09:28 +00:00
To omit only the comments from the feedback section, use the following key in
the front matter:
2018-10-18 11:58:55 +00:00
```yaml
---
comments: false
---
```
2020-09-14 15:09:28 +00:00
We're hiding comments only in main index pages, such as [the main documentation index ](../../README.md ),
since its content is too broad to comment on. Before omitting Disqus, you must
check with a technical writer.
2018-10-18 11:58:55 +00:00
2020-09-14 15:09:28 +00:00
Note that after adding `feedback: false` to the front matter, it will omit
2018-10-18 11:58:55 +00:00
Disqus, therefore, don't add both keys to the same document.
2020-09-14 15:09:28 +00:00
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**.
2020-07-22 21:09:50 +00:00
2021-02-02 00:09:14 +00:00
### Guidelines for good practices
2020-07-22 21:09:50 +00:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36576/) in GitLab 13.2 as GitLab Development documentation.
2020-09-14 15:09:28 +00:00
*Good practice* examples demonstrate encouraged ways of writing code while
comparing with examples of practices to avoid. These examples are labeled as
*Bad* or *Good* . In GitLab development guidelines, when presenting the cases,
it's recommended to follow a *first-bad-then-good* strategy. First demonstrate
the *Bad* practice (how things *could* be done, which is often still working
code), and then how things *should* be done better, using a *Good* example. This
is typically an improved example of the same code.
2020-07-22 21:09:50 +00:00
Consider the following guidelines when offering examples:
2020-09-14 15:09:28 +00:00
- First, offer the *Bad* example, and then the *Good* one.
2020-07-22 21:09:50 +00:00
- When only one bad case and one good case is given, use the same code block.
2020-09-14 15:09:28 +00:00
- When more than one bad case or one good case is offered, use separated code
blocks for each. With many examples being presented, a clear separation helps
the reader to go directly to the good part. Consider offering an explanation
(for example, a comment, or a link to a resource) on why something is bad
practice.
2020-07-22 21:09:50 +00:00
- Better and best cases can be considered part of the good case(s) code block.
2020-09-14 15:09:28 +00:00
In the same code block, precede each with comments: `# Better` and `# Best` .
2020-08-05 12:09:45 +00:00
2020-09-14 15:09:28 +00:00
Although the bad-then-good approach is acceptable for the GitLab development
guidelines, do not use it for user documentation. For user documentation, use
*Do* and *Don't* . For examples, see the [Pajamas Design System ](https://design.gitlab.com/content/punctuation/ ).