- Start with an h2 (`##`), break complex steps into small steps using
subheadings h3 > h4 > h5 > h6. _Never skip a hierarchy level, such
as h2 > h4_, as it will break the TOC and may affect the breadcrumbs.
- Use short and descriptive headings (up to ~50 chars). You can use one
single heading like `## Configure X` for instructions when the feature
is simple and the document is short.
Include example code or configurations when needed. Use Markdown to wrap code
blocks with [syntax highlighting](../../user/markdown.md#colored-code-and-syntax-highlighting).
Example topic:
## Create a teddy bear
Start by writing a sentence or two about _why_ someone would want to perform this task.
It's not always possible, but is a good practice. For example:
Create a teddy bear when you need something to hug.
Follow this information with the task steps.
Create a teddy bear when you need something to hug. (Include the reason why you
might do the task.)
To create a teddy bear:
...
...
@@ -142,40 +133,40 @@ To create a teddy bear:
1. Expand **This** and click **This**.
1. Do another step.
After the numbered list, add a sentence with the expected result, if it
is not obvious, and any next steps. For example:
The teddy bear is now in the kitchen, in the cupboard above the sink.
The teddy bear is now in the kitchen, in the cupboard above the sink. _(This is the result.)_
You can retrieve the teddy bear and put it on the couch with the other animals.
You can retrieve the teddy bear and put it on the couch with the other animals. _(These are next steps.)_
Screenshots are not necessary. They are difficult to keep up-to-date and can clutter the page.
Screenshots are not necessary. They are difficult to keep up-to-date and can
clutter the page.
<!-- ## Troubleshooting
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 doc comments with
questions that you know someone might ask.
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.
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. -->
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. -->
---
Notes:
- (1): Apply the [tier badges](styleguide.md#product-badges) accordingly
- (1): Apply the [tier badges](styleguide.md#product-badges) accordingly.
- (2): Apply the correct format for the
[GitLab version that introduces the feature](styleguide.md#gitlab-versions-and-tiers)
[GitLab version that introduces the feature](styleguide.md#gitlab-versions-and-tiers).
```
## Help and feedback section
The "help and feedback" section (introduced by [!319](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/319)) displayed at the end of each document
can be omitted from the doc by adding a key into the its front matter:
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:
```yaml
---
...
...
@@ -183,8 +174,8 @@ 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.
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
...
...
@@ -192,8 +183,8 @@ We also have integrated the docs site with Disqus (introduced by
To omit only the comments from the feedback section, use the following
key on the front matter:
To omit only the comments from the feedback section, use the following key in
the front matter:
```yaml
---
...
...
@@ -201,36 +192,42 @@ comments: false
---
```
We are only hiding comments 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.
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.
Note that once `feedback: false` is added to the front matter, it will automatically omit
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**.
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](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36576/) 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 is 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.
*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, then the "Good" one.
- 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, a link to a resource, etc.) on why something is bad practice.
- 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 case(s) code block.
In the same code block, precede each with comments: `# Better` and `# Best`.
In the same code block, precede each with comments: `# Better` and `# Best`.
NOTE: **Note:**
While 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 example, see the
