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

stage	group	info	description
none	Style Guide	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	What to include in GitLab documentation pages.

Documentation topic types (CTRT)

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 (CTRT):

• Concept
• Task
• Reference
• Troubleshooting

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.

A page might also contain only one type of information. These pages are generally one of our other content types.

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 concept before.

Don't tell them how to do this thing. Tell them what it is.

If you start describing another concept, start a new concept and link to it.

Concepts should be in this format:

# Title (a noun, like "Widgets")

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 should be about one concept only.

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.

Task

A task gives instructions for how to complete a procedure.

Tasks should be in this format:

# Title (starts with an active verb, like "Create a widget" or "Delete a widget")

Do this task when you want to...

Prerequisites (optional):

- Thing 1
- Thing 2
- Thing 3

To do this task:

1. Location then action. (Go to this menu, then select this item.)
1. Another step.
1. Another step.

Task result (optional). Next steps (optional).

Here is an example.

# Create an issue

Create an issue when you want to track bugs or future work.

Prerequisites:

- You must have at least the Developer role for the project.

To create an issue:

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**.

Task headings

For the heading text, use the structure active verb + noun. For example, Create an issue.

If you have several tasks on a page that share prerequisites, you can use the title Prerequisites and link to it.

Reference

Reference information should be in an easily-scannable format, like a table or list. It's similar to a dictionary or encyclopedia entry.

# Title (a noun, like "Pipeline settings" or "Administrator options")

Introductory sentence.

| Setting | Description |
|---------|-------------|
| **Name** | Descriptive sentence about the setting. |

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.

Troubleshooting

Troubleshooting topics should be the last topics on a page.

Troubleshooting can be one of three categories:

• An introductory topic. This topic introduces the troubleshooting section of a page. For example:

  ## Troubleshooting
  
  When working with <x feature>, you might encounter the following issues.
  

• Troubleshooting task. The title should be similar to a standard task. For example, "Run debug tools" or "Verify syntax."

• Troubleshooting reference. This information includes the error message. For example:

  ### The error message or a description of it
  
  You might get an error that states <error message>.
  
  This issue occurs when...
  
  The workaround is...
  

  If multiple causes or workarounds exist, consider putting them into a table format. If you use the exact error message, surround it in backticks so it's styled as code.

If a page has more than five troubleshooting topics, put the content on a separate page that has troubleshooting information exclusively. Name the page Troubleshooting <featurename>.

Troubleshooting headings

For the heading of a Troubleshooting reference topic:

• Consider including at least a partial error message.
• Use fewer than 70 characters.

If you do not put the full error in the title, include it in the body text.

Related topics

If inline links are not sufficient, you can create a topic called Related topics and include an unordered list of related topics. This topic should be above the Troubleshooting section.

# Related topics

- [Configure your pipeline](link-to-topic)
- [Trigger a pipeline manually](link-to-topic)

General heading text guidelines

In general, for heading text:

• Be clear and direct. Make every word count.
• Use articles and prepositions.
• Follow 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.

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. These include:

• Tutorials
• Get started 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 to document new features.

Tutorials should be in this format:

# 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:

1. [Do the first task](#do-the-first-task)
1. [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.
1. Another step.
1. 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.
1. Another step.
1. 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:

# 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.

Topics and resources pages

This page has a list of links that point to important sections of documentation for a specific GitLab feature or tool.

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:

• 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:

# 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

This section (introduced in GitLab 11.4) is displayed at the end of each document and can be omitted by adding a key into the front matter:

---
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

We also have integrated the docs site with Disqus (introduced by !151), allowing our users to post comments.

To omit only the comments from the feedback section, use the following key in the front matter:

---
comments: false
---

We're hiding comments only in main index pages, such as the main documentation index, since its content is too broad to comment on. Before omitting Disqus, you must check with a technical writer.

Note that after adding feedback: false to the front matter, it will omit Disqus, therefore, don't add both keys to the same document.

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

Introduced in GitLab 13.2 as GitLab Development documentation.

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.

Consider the following guidelines when offering examples:

• First, offer the Bad example, and then the Good one.
• When only one bad case and one good case is given, use the same code block.
• 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.
• Better and best cases can be considered part of the good cases' code block. In the same code block, precede each with comments: # Better and # Best.

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.