debian-mirror-gitlab/doc/development/documentation/structure.md

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

383 lines
11 KiB
Markdown
Raw Normal View History

2018-11-20 20:47:30 +05:30
---
2020-11-24 15:15:51 +05:30
stage: none
group: Style Guide
2021-02-22 17:27:13 +05:30
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
2019-02-15 15:39:39 +05:30
description: What to include in GitLab documentation pages.
2018-11-20 20:47:30 +05:30
---
2022-04-04 11:22:00 +05:30
# Documentation topic types (CTRT)
2018-11-20 20:47:30 +05:30
2021-09-30 23:02:18 +05:30
At GitLab, we have not traditionally used types for our content. However, we are starting to
2022-04-04 11:22:00 +05:30
move in this direction, and we now use four primary topic types (CTRT):
2018-11-20 20:47:30 +05:30
2021-03-11 19:13:27 +05:30
- [Concept](#concept)
- [Task](#task)
- [Reference](#reference)
- [Troubleshooting](#troubleshooting)
2018-11-20 20:47:30 +05:30
2021-09-30 23:02:18 +05:30
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.
2018-11-20 20:47:30 +05:30
2021-09-30 23:02:18 +05:30
A page might also contain only one type of information. These pages are generally one of our
[other content types](#other-types-of-content).
2018-11-20 20:47:30 +05:30
2021-03-11 19:13:27 +05:30
## Concept
2018-11-20 20:47:30 +05:30
2021-09-30 23:02:18 +05:30
A concept introduces a single feature or concept.
2018-11-20 20:47:30 +05:30
2021-03-11 19:13:27 +05:30
A concept should answer the questions:
2020-11-24 15:15:51 +05:30
2021-03-11 19:13:27 +05:30
- What is this?
- Why would I use it?
2018-11-20 20:47:30 +05:30
2021-09-30 23:02:18 +05:30
Think of everything someone might want to know if they've never heard of this concept before.
2018-11-20 20:47:30 +05:30
2021-04-29 21:17:54 +05:30
Don't tell them **how** to do this thing. Tell them **what it is**.
2019-02-15 15:39:39 +05:30
2021-09-30 23:02:18 +05:30
If you start describing another concept, start a new concept and link to it.
2021-03-11 19:13:27 +05:30
2021-09-30 23:02:18 +05:30
Concepts should be in this format:
2021-03-11 19:13:27 +05:30
```markdown
# Title (a noun, like "Widgets")
2019-02-15 15:39:39 +05:30
2021-03-11 19:13:27 +05:30
A paragraph that explains what this thing is.
2020-11-24 15:15:51 +05:30
2021-03-11 19:13:27 +05:30
Another paragraph that explains what this thing is.
2018-11-20 20:47:30 +05:30
2021-03-11 19:13:27 +05:30
Remember, if you start to describe about another concept, stop yourself.
2021-09-30 23:02:18 +05:30
Each concept should be about one concept only.
2021-03-11 19:13:27 +05:30
```
2018-11-20 20:47:30 +05:30
2022-07-23 23:45:48 +05:30
### Concept headings
For the heading text, use a noun. For example, `Widgets` or `GDK dependency management`.
If a noun is ambiguous, you can add a gerund. For example, `Documenting versions` instead of `Versions`.
Avoid these heading titles:
- `Overview` or `Introduction`. Instead, use a more specific
noun or phrase that someone would search for.
- `Use cases`. Instead, incorporate the information as part of the concept.
- `How it works`. Instead, use a noun followed by `workflow`. For example, `Merge request workflow`.
2021-03-11 19:13:27 +05:30
## Task
2018-11-20 20:47:30 +05:30
2021-09-30 23:02:18 +05:30
A task gives instructions for how to complete a procedure.
2019-02-15 15:39:39 +05:30
2021-09-30 23:02:18 +05:30
Tasks should be in this format:
2018-11-20 20:47:30 +05:30
2021-03-11 19:13:27 +05:30
```markdown
# Title (starts with an active verb, like "Create a widget" or "Delete a widget")
2018-11-20 20:47:30 +05:30
2021-03-11 19:13:27 +05:30
Do this task when you want to...
2020-10-24 23:57:45 +05:30
2021-03-11 19:13:27 +05:30
Prerequisites (optional):
2020-11-24 15:15:51 +05:30
2021-03-11 19:13:27 +05:30
- Thing 1
- Thing 2
- Thing 3
2020-10-24 23:57:45 +05:30
2021-03-11 19:13:27 +05:30
To do this task:
2018-11-20 20:47:30 +05:30
2021-03-11 19:13:27 +05:30
1. Location then action. (Go to this menu, then select this item.)
1. Another step.
1. Another step.
2020-10-24 23:57:45 +05:30
2021-03-11 19:13:27 +05:30
Task result (optional). Next steps (optional).
```
2020-10-24 23:57:45 +05:30
2021-03-11 19:13:27 +05:30
Here is an example.
2020-10-24 23:57:45 +05:30
2021-03-11 19:13:27 +05:30
```markdown
# Create an issue
2020-10-24 23:57:45 +05:30
2021-03-11 19:13:27 +05:30
Create an issue when you want to track bugs or future work.
2020-10-24 23:57:45 +05:30
2021-03-11 19:13:27 +05:30
Prerequisites:
2020-10-24 23:57:45 +05:30
2022-01-26 12:08:38 +05:30
- You must have at least the Developer role for the project.
2020-10-24 23:57:45 +05:30
2021-03-11 19:13:27 +05:30
To create an issue:
2020-10-24 23:57:45 +05:30
2021-09-30 23:02:18 +05:30
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.)
2021-06-08 01:23:25 +05:30
1. Select **Create issue**.
2018-11-20 20:47:30 +05:30
2021-03-11 19:13:27 +05:30
The issue is created. You can view it by going to **Issues > List**.
```
2018-11-20 20:47:30 +05:30
2022-07-23 23:45:48 +05:30
### Task headings
For the heading text, use the structure `active verb` + `noun`.
For example, `Create an issue`.
2021-09-30 23:02:18 +05:30
If you have several tasks on a page that share prerequisites, you can use the title
2022-07-23 23:45:48 +05:30
`Prerequisites` and link to it.
2021-06-08 01:23:25 +05:30
2021-03-11 19:13:27 +05:30
## Reference
2019-02-15 15:39:39 +05:30
2021-09-30 23:02:18 +05:30
Reference information should be in an easily-scannable format,
2021-03-11 19:13:27 +05:30
like a table or list. It's similar to a dictionary or encyclopedia entry.
2018-12-13 13:39:08 +05:30
2021-03-11 19:13:27 +05:30
```markdown
# Title (a noun, like "Pipeline settings" or "Administrator options")
2018-11-20 20:47:30 +05:30
2021-03-11 19:13:27 +05:30
Introductory sentence.
2018-11-20 20:47:30 +05:30
2021-03-11 19:13:27 +05:30
| Setting | Description |
|---------|-------------|
| **Name** | Descriptive sentence about the setting. |
2018-12-13 13:39:08 +05:30
```
2022-07-23 23:45:48 +05:30
### Reference headings
Reference headings are usually nouns.
Avoid these heading titles:
- `Important notes`. Instead, incorporate this information
closer to where it belongs. For example, this information might be a prerequisite
for a task, or information about a concept.
- `Limitations`. Instead, move the content near other similar information.
If you must, you can use the title `Known issues`.
2021-06-08 01:23:25 +05:30
2021-03-11 19:13:27 +05:30
## Troubleshooting
2021-09-30 23:02:18 +05:30
Troubleshooting can be one of two categories:
2021-03-11 19:13:27 +05:30
2021-09-30 23:02:18 +05:30
- **Troubleshooting task.** This information is written the same way as a [standard task](#task).
2021-03-11 19:13:27 +05:30
For example, "Run debug tools" or "Verify syntax."
2021-09-30 23:02:18 +05:30
- **Troubleshooting reference.** This information has a specific format.
2021-03-11 19:13:27 +05:30
2021-09-30 23:02:18 +05:30
Troubleshooting reference information should be in this format:
2021-03-11 19:13:27 +05:30
```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...
```
2022-07-23 23:45:48 +05:30
If multiple causes or workarounds exist, consider putting them into a table format.
### Troubleshooting headings
2021-09-30 23:02:18 +05:30
For the heading:
2021-04-29 21:17:54 +05:30
2021-09-30 23:02:18 +05:30
- Consider including at least a partial error message.
2021-04-29 21:17:54 +05:30
- Use fewer than 70 characters.
2021-09-30 23:02:18 +05:30
If you do not put the full error in the title, include it in the body text.
2022-07-23 23:45:48 +05:30
## General heading text guidelines
In general, for heading text:
- 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 headings. For example, if the page is about merge requests,
instead of `Troubleshooting merge requests`, use only `Troubleshooting`.
See also [guidelines for headings in Markdown](styleguide/index.md#headings-in-markdown).
2021-11-18 22:05:49 +05:30
2021-09-30 23:02:18 +05:30
## Other types of content
There are other types of content in the GitLab documentation that don't
2022-04-04 11:22:00 +05:30
classify as one of the four primary [topic types](#documentation-topic-types-ctrt).
2021-09-30 23:02:18 +05:30
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.
2022-04-04 11:22:00 +05:30
Always use the primary [topic types](#documentation-topic-types-ctrt) to document new features.
2021-09-30 23:02:18 +05:30
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:
2021-10-27 15:23:28 +05:30
1. [Do the first task](#do-the-first-task)
1. [Do the second task](#do-the-second-task)
2021-09-30 23:02:18 +05:30
Prerequisites (optional):
- Thing 1
- Thing 2
- Thing 3
## Do the first task
To do step 1:
1. First step.
2021-10-27 15:23:28 +05:30
1. Another step.
1. Another step.
2021-09-30 23:02:18 +05:30
## 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.
2021-10-27 15:23:28 +05:30
1. Another step.
1. Another step.
2021-09-30 23:02:18 +05:30
```
### 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.
```
2021-04-29 21:17:54 +05:30
2021-12-11 22:18:48 +05:30
### Related topics
If inline links are not sufficient, you can create a topic called **Related topics**
2022-07-16 23:28:13 +05:30
and include an unordered list of related topics. This topic should be above the Troubleshooting section.
2021-12-11 22:18:48 +05:30
```markdown
# Related topics
- [Configure your pipeline](link-to-topic)
- [Trigger a pipeline manually](link-to-topic)
```
2021-09-30 23:02:18 +05:30
### Topics and resources pages
2021-03-11 19:13:27 +05:30
2021-12-11 22:18:48 +05:30
This page has a list of links that point to important sections
2021-09-30 23:02:18 +05:30
of documentation for a specific GitLab feature or tool.
2021-03-11 19:13:27 +05:30
2021-09-30 23:02:18 +05:30
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:
2021-03-11 19:13:27 +05:30
2021-09-30 23:02:18 +05:30
- 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
```
2021-03-11 19:13:27 +05:30
2021-09-30 23:02:18 +05:30
## Help and feedback section
2018-12-13 13:39:08 +05:30
2020-11-24 15:15:51 +05:30
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-12-13 13:39:08 +05:30
```yaml
---
feedback: false
---
```
2020-11-24 15:15:51 +05:30
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-12-13 13:39:08 +05:30
2021-09-30 23:02:18 +05:30
### Disqus
2018-12-13 13:39:08 +05:30
We also have integrated the docs site with Disqus (introduced by
2020-03-13 15:44:24 +05:30
[!151](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/151)),
2018-12-13 13:39:08 +05:30
allowing our users to post comments.
2020-11-24 15:15:51 +05:30
To omit only the comments from the feedback section, use the following key in
the front matter:
2018-12-13 13:39:08 +05:30
```yaml
---
comments: false
---
```
2021-09-30 23:02:18 +05:30
We're hiding comments only in main index pages, such as [the main documentation index](../../index.md),
2020-11-24 15:15:51 +05:30
since its content is too broad to comment on. Before omitting Disqus, you must
check with a technical writer.
2018-12-13 13:39:08 +05:30
2020-11-24 15:15:51 +05:30
Note that after adding `feedback: false` to the front matter, it will omit
2018-12-13 13:39:08 +05:30
Disqus, therefore, don't add both keys to the same document.
2020-11-24 15:15:51 +05:30
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-10-24 23:57:45 +05:30
2021-09-30 23:02:18 +05:30
## Guidelines for good practices
2020-10-24 23:57:45 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36576/) in GitLab 13.2 as GitLab Development documentation.
2020-11-24 15:15:51 +05:30
*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-10-24 23:57:45 +05:30
Consider the following guidelines when offering examples:
2020-11-24 15:15:51 +05:30
- First, offer the *Bad* example, and then the *Good* one.
2020-10-24 23:57:45 +05:30
- When only one bad case and one good case is given, use the same code block.
2020-11-24 15:15:51 +05:30
- 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.
2022-07-16 23:28:13 +05:30
- Better and best cases can be considered part of the good cases' code block.
2020-11-24 15:15:51 +05:30
In the same code block, precede each with comments: `# Better` and `# Best`.
2020-10-24 23:57:45 +05:30
2020-11-24 15:15:51 +05:30
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/).