Skip to content

G
gitlab-ce
Commit c37d7cd8 authored by Suzanne Selhorn's avatar Suzanne Selhorn
Browse files
Options

Merge branch 'docs-style-guide-update-standard' into 'master' 

Doc: Update style guide to be based more on itself

See merge request gitlab-org/gitlab!44799
parents 30e2fe11 76af63e8
Show whitespace changes
Inline Side-by-side
Showing with 115 additions and 118 deletions
doc/development/documentation/styleguide.md
View file @ c37d7cd8
......@@ -48,7 +48,7 @@ documentation.
### All information
Include problem-solving actions that may address rare cases or be considered
*risky*, so long as proper context is provided in the form of fully detailed
_risky_, so long as proper context is provided in the form of fully detailed
warnings and caveats. This kind of content should be included as it could be
helpful to others and, when properly explained, its benefits outweigh the risks.
If you think you have found an exception to this rule, contact the
......@@ -101,9 +101,8 @@ of truth and explain why it is important to consume the information.
### Organize by topic, not by type
Beyond top-level audience-type folders (for example, `administration`), we
organize content by topic, not by type, so it can be located as easily as
possible within the single-source-of-truth (SSOT) section for the subject
matter.
organize content by topic, not by type, so it can be located in the
single-source-of-truth (SSOT) section for the subject matter.
For example, do not create groupings of similar media types. For example:
......@@ -118,7 +117,7 @@ cross-link between any related content.
### Docs-first methodology
We employ a *documentation-first methodology* to help ensure the documentation
We employ a _documentation-first methodology_ to help ensure the documentation
remains a complete and trusted resource, and to make communicating about the use
of GitLab more efficient.
......@@ -127,8 +126,7 @@ of GitLab more efficient.
- When you encounter new information not available in GitLab’s documentation (for
example, when working on a support case or testing a feature), your first step
should be to create a merge request (MR) to add this information to the
documentation. You can then share the MR in order to communicate this
information.
documentation. You can then share the MR to communicate this information.
New information that would be useful toward the future usage or troubleshooting
of GitLab should not be written directly in a forum or other messaging system,
......@@ -147,11 +145,11 @@ If you have questions when considering, authoring, or editing documentation, ask
the Technical Writing team on Slack in `#docs` or in GitLab by mentioning the
writer for the applicable [DevOps stage](https://about.gitlab.com/handbook/product/product-categories/#devops-stages).
Otherwise, forge ahead with your best effort. It does not need to be perfect;
the team is happy to review and improve upon your content. Please review the
the team is happy to review and improve upon your content. Review the
[Documentation guidelines](index.md) before you begin your first documentation MR.
Having a knowledge base in any form that is separate from the documentation would
be against the documentation-first methodology because the content would overlap with
Having a knowledge base in any form that's separate from the documentation would
be against the documentation-first methodology, because the content would overlap with
the documentation.
## Markdown
......@@ -163,17 +161,17 @@ Markdown rendering engine. For a complete Kramdown reference, see the
[GitLab Markdown Kramdown Guide](https://about.gitlab.com/handbook/markdown-guide/).
The [`gitlab-kramdown`](https://gitlab.com/gitlab-org/gitlab_kramdown) Ruby gem
will support all [GFM markup](../../user/markdown.md) in the future. That is,
will support all [GFM markup](../../user/markdown.md) in the future, which is
all markup supported for display in the GitLab application itself. For now, use
regular Markdown markup, following the rules in the linked style guide.
Note that Kramdown-specific markup (for example, `{:.class}`) will not render
Note that Kramdown-specific markup (for example, `{:.class}`) doesn't render
properly on GitLab instances under [`/help`](index.md#gitlab-help).
### HTML in Markdown
Hard-coded HTML is valid, although it's discouraged from being used while we
have `/help`. HTML is permitted as long as:
have `/help`. HTML is permitted if:
- There's no equivalent markup in Markdown.
- Advanced tables are necessary.
......@@ -238,14 +236,15 @@ Our goal is to have a clear hierarchical structure with meaningful URLs like
`docs.gitlab.com/user/project/merge_requests/`. With this pattern, you can
immediately tell that you are navigating to user-related documentation about
Project features; specifically about Merge Requests. Our site's paths match
those of our repository, so the clear structure also makes documentation easier to update.
those of our repository, so the clear structure also makes documentation easier
to update.
The table below shows what kind of documentation goes where.
Put files for a specific product area into the related folder:
| Directory | What belongs here |
|:----------------------|:----------------------------------------------------------------------------------------------------------------------------------------|
| `doc/user/` | User related documentation. Anything that can be done within the GitLab user interface goes here, including usage of the `/admin` interface. |
| `doc/administration/` | Documentation that requires the user to have access to the server where GitLab is installed. The admin settings that can be accessed via GitLab's interface exist under `doc/user/admin_area/`. |
| `doc/administration/` | Documentation that requires the user to have access to the server where GitLab is installed. The admin settings that can be accessed by using GitLab's interface exist under `doc/user/admin_area/`. |
| `doc/api/` | API related documentation. |
| `doc/development/` | Documentation related to the development of GitLab, whether contributing code or documentation. Related process and style guides should go here. |
| `doc/legal/` | Legal documents about contributing to GitLab. |
......@@ -255,9 +254,11 @@ The table below shows what kind of documentation goes where.
### Work with directories and files
Refer to the following items when working with directories and files:
1. When you create a new directory, always start with an `index.md` file.
Do not use another file name and *do not* create `README.md` files.
1. *Do not* use special characters and spaces, or capital letters in file
Don't use another file name and _do not_ create `README.md` files.
1. _Do not_ use special characters and spaces, or capital letters in file
names, directory names, branch names, and anything that generates a path.
1. When creating or renaming a file or directory and it has more than one word
in its name, use underscores (`_`) instead of spaces or dashes. For example,
......@@ -270,17 +271,17 @@ The table below shows what kind of documentation goes where.
`development`.
1. The `doc/user/` directory has five main subdirectories: `project/`, `group/`,
`profile/`, `dashboard/` and `admin_area/`.
1. `doc/user/project/` should contain all project related documentation.
1. `doc/user/group/` should contain all group related documentation.
1. `doc/user/profile/` should contain all profile related documentation.
- `doc/user/project/` should contain all project related documentation.
- `doc/user/group/` should contain all group related documentation.
- `doc/user/profile/` should contain all profile related documentation.
Every page you would navigate under `/profile` should have its own document,
for example, `account.md`, `applications.md`, or `emails.md`.
1. `doc/user/dashboard/` should contain all dashboard related documentation.
1. `doc/user/admin_area/` should contain all admin related documentation
- `doc/user/dashboard/` should contain all dashboard related documentation.
- `doc/user/admin_area/` should contain all admin related documentation
describing what can be achieved by accessing GitLab's admin interface
(_not to be confused with `doc/administration` where server access is
required_).
1. Every category under `/admin/application_settings/` should have its
- Every category under `/admin/application_settings/` should have its
own document located at `doc/user/admin_area/settings/`. For example,
the **Visibility and Access Controls** category should have a document
located at `doc/user/admin_area/settings/visibility_and_access_controls.md`.
......@@ -290,12 +291,12 @@ The table below shows what kind of documentation goes where.
1. The `/university/` directory is *deprecated* and the majority of its documentation
has been moved.
If you are unsure where to place a document or a content addition, this should
not stop you from authoring and contributing. You can use your best judgment and
then ask the reviewer of your MR to confirm your decision, and/or ask a
technical writer at any stage in the process. The technical writing team will
review all documentation changes, regardless, and can move content if there is a
better place for it.
If you're unsure where to place a document or a content addition, this shouldn't
stop you from authoring and contributing. Use your best judgment, and then ask
the reviewer of your MR to confirm your decision, or ask a technical writer at
any stage in the process. The technical writing team will review all
documentation changes, regardless, and can move content if there is a better
place for it.
### Avoid duplication
......@@ -350,11 +351,11 @@ Use sentence case. For example:
#### UI text
When referring to specific user interface text, like a button label or menu
item, use the same capitalization that is displayed in the user interface.
item, use the same capitalization that's displayed in the user interface.
Standards for this content are listed in the [Pajamas Design System Content section](https://design.gitlab.com/content/punctuation/)
and typically match what is called for in this Documentation Style Guide.
and typically match what's called for in this Documentation Style Guide.
If you think there is a mistake in the way the user interface text is styled,
If you think there's a mistake in the way the user interface text is styled,
create an issue or an MR to propose a change to the user interface text.
#### Feature names
......@@ -413,8 +414,8 @@ references to user interface elements. For example:
### Inclusive language
We strive to create documentation that is inclusive. This section includes
guidance and examples in the following categories:
We strive to create documentation that's inclusive. This section includes
guidance and examples for the following categories:
- [Gender-specific wording](#avoid-gender-specific-wording).
(Tested in [`InclusionGender.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionGender.yml).)
......@@ -488,11 +489,11 @@ For more information see the following [Internet Draft specification](https://to
### Fake user information
You may need to include user information in entries such as a REST call or user profile.
**Do not** use real user information or email addresses in GitLab documentation. For email
_Do not_ use real user information or email addresses in GitLab documentation. For email
addresses and names, do use:
- **Email addresses**: Use an email address ending in `example.com`.
- **Names**: Use strings like `example_username`. Alternatively, use diverse or
- _Email addresses_: Use an email address ending in `example.com`.
- _Names_: Use strings like `example_username`. Alternatively, use diverse or
non-gendered names with common surnames, such as `Sidney Jones`, `Zhang Wei`,
or `Alex Garcia`.
......@@ -536,8 +537,8 @@ tenses, words, and phrases:
content is accessible to more readers.
- Don't write in the first person singular.
(Tested in [`FirstPerson.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FirstPerson.yml).)
- Instead of "I" or "me," use "we," "you," "us," or "one."
- When possible, stay user focused by writing in the second person ("you" or
- Instead of _I_ or _me_, use _we_, _you_, _us_, or _one_.
- When possible, stay user focused by writing in the second person (_you_ or
the imperative).
- Don't overuse "that". In many cases, you can remove "that" from a sentence
and improve readability.
......@@ -656,9 +657,7 @@ Some contractions, however, should be avoided:
### Punctuation
Review the general punctuation rules for the GitLab documentation in the
following table. Check specific punctuation rules for [lists](#lists) below.
Additional examples are available in the [Pajamas guide for punctuation](https://design.gitlab.com/content/punctuation/).
Follow these guidelines for punctuation:
<!-- vale gitlab.Repetition = NO -->
......@@ -702,7 +701,7 @@ To stop the command, press <kbd>Ctrl</kbd>+<kbd>C</kbd>.
## Lists
- Always start list items with a capital letter, unless they are parameters or
- Always start list items with a capital letter, unless they're parameters or
commands that are in backticks, or similar.
- Always leave a blank line before and after a list.
- Begin a line with spaces (not tabs) to denote a [nested sub-item](#nesting-inside-a-list-item).
......@@ -735,11 +734,11 @@ This is a list of available features:
- Use dashes (`-`) for unordered lists instead of asterisks (`*`).
- Prefix `1.` to every item in an ordered list. When rendered, the list items
will appear with sequential numbering automatically.
will appear with sequential numbering.
### Punctuation
- Do not add commas (`,`) or semicolons (`;`) to the end of list items.
- Don't add commas (`,`) or semicolons (`;`) to the ends of list items.
- Only add periods to the end of a list item if the item consists of a complete
sentence. The [definition of full sentence](https://www2.le.ac.uk/offices/ld/all-resources/writing/grammar/grammar-guides/sentence)
is: _"a complete sentence always contains a verb, expresses a complete idea, and makes sense standing alone"_.
......@@ -841,8 +840,8 @@ For ordered lists, use three spaces for each level of indentation:
````
You can nest full lists inside other lists using the same rules as above. If you
want to mix types, that is also possible, as long as you don't mix items at the
same level:
want to mix types, that's also possible, if you don't mix items at the same
level:
```markdown
1. Ordered list item one.
......@@ -863,7 +862,7 @@ same level:
Tables should be used to describe complex information in a straightforward
manner. Note that in many cases, an unordered list is sufficient to describe a
list of items with a single, simple description per item. But, if you have data
that is best described by a matrix, tables are the best choice for use.
that's best described by a matrix, tables are the best choice.
### Creation guidelines
......@@ -907,12 +906,12 @@ Valid for Markdown content only, not for front matter entries:
- Quote within a quote: double quotes (`"`) wrap single quotes (`'`). Example:
"I am 'quoting' something within a quote".
For other punctuation rules, please refer to the
For other punctuation rules, refer to the
[GitLab UX guide](https://design.gitlab.com/content/punctuation/).
## Headings
- Add **only one H1** in each document, by adding `#` at the beginning of
- Add _only one H1_ in each document, by adding `#` at the beginning of
it (when using Markdown). The `h1` will be the document `<title>`.
- Start with an `h2` (`##`), and respect the order `h2` > `h3` > `h4` > `h5` > `h6`.
Never skip the hierarchy level, such as `h2` > `h4`
......@@ -959,12 +958,13 @@ GitLab documentation from both the GitLab application and external sites.
### Anchor links
Headings generate anchor links automatically when rendered. `## This is an example`
generates the anchor `#this-is-an-example`.
Headings generate anchor links when rendered. `## This is an example` generates
the anchor `#this-is-an-example`.
NOTE: **Note:**
[Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39717) in GitLab 13.4, [product badges](#product-badges) used in headings aren't included in the
generated anchor links. For example, when you link to
[Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39717) in
GitLab 13.4, [product badges](#product-badges) used in headings aren't included
in the generated anchor links. For example, when you link to
`## This is an example **(CORE)**`, use the anchor `#this-is-an-example`.
Keep in mind that the GitLab user interface links to many documentation pages
......@@ -985,7 +985,7 @@ Important:
- Do not link to `h1` headings.
Note that, with Kramdown, it is possible to add a custom ID to an HTML element
with Markdown markup, but they **do not** work in GitLab's `/help`. Therefore,
with Markdown markup, but they _do not_ work in GitLab's `/help`. Therefore,
do not use this option until further notice.
## Links
......@@ -1012,7 +1012,7 @@ We include guidance for links in the following categories:
### Basic link criteria
- Use inline link Markdown markup `[Text](https://example.com)`.
It's easier to read, review, and maintain. *Do not* use `[Text][identifier]`.
It's easier to read, review, and maintain. _Do not_ use `[Text][identifier]`.
- Use [meaningful anchor texts](https://www.futurehosting.com/blog/links-should-have-meaningful-anchor-text-heres-why/).
For example, instead of writing something like `Read more about GitLab Issue Boards [here](LINK)`,
......@@ -1133,7 +1133,7 @@ Instead:
- Contained in a confidential issue.
- Requires special permission to a project to view.
- Provide a link in back ticks (`` ` ``) so that those with access to the issue
can easily navigate to it.
can navigate to it.
Example:
......@@ -1149,8 +1149,8 @@ the commit link ensures the user lands on the line you're referring to. The
**Permalink** button, which is available when viewing a file within a project,
makes it easy to generate a link to the most recent commit of the given file.
- *Do:* `[link to line 3](https://gitlab.com/gitlab-org/gitlab/-/blob/11f17c56d8b7f0b752562d78a4298a3a95b5ce66/.gitlab/issue_templates/Feature%20proposal.md#L3)`
- *Don't:* `[link to line 3](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/issue_templates/Feature%20proposal.md#L3).`
- _Do_: `[link to line 3](https://gitlab.com/gitlab-org/gitlab/-/blob/11f17c56d8b7f0b752562d78a4298a3a95b5ce66/.gitlab/issue_templates/Feature%20proposal.md#L3)`
- _Don't_: `[link to line 3](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/issue_templates/Feature%20proposal.md#L3).`
If that linked expression is no longer in that line of the file due to additional
commits, you can still search the file for that query. In this case, update the
......@@ -1194,19 +1194,19 @@ they need to interact with the application.
When you take screenshots:
- *Capture the most relevant area of the page.* Don't include unnecessary white
- _Capture the most relevant area of the page._ Don't include unnecessary white
space or areas of the page that don't help illustrate the point. The left
sidebar of the GitLab user interface can change, so don't include the sidebar
if it's not necessary.
- *Keep it small.* If you don't need to show the full width of the screen, don't.
- _Keep it small._ If you don't need to show the full width of the screen, don't.
A value of 1000 pixels is a good maximum width for your screenshot image.
- *Be consistent.* Coordinate screenshots with the other screenshots already on
- _Be consistent._ Coordinate screenshots with the other screenshots already on
a documentation page. For example, if other screenshots include the left
sidebar, include the sidebar in all screenshots.
### Save the image
- Save the image with a lowercase file name that is descriptive of the feature
- Save the image with a lowercase file name that's descriptive of the feature
or concept in the image. If the image is of the GitLab interface, append the
GitLab version to the file name, based on the following format:
`image_name_vX_Y.png`. For example, for a screenshot taken from the pipelines
......@@ -1235,7 +1235,7 @@ documentation site. For accessibility and SEO, use [descriptions](https://webaim
that:
- Are accurate, succinct, and unique.
- Don't use *image of …* or *graphic of…* to describe the image.
- Don't use _image of…_ or _graphic of…_ to describe the image.
### Remove image shadow
......@@ -1298,7 +1298,7 @@ for videos before reading:
For an overview, see [Video Title](link-to-video).
```
You can link any up-to-date video that is useful to the GitLab user.
You can link any up-to-date video that's useful to the GitLab user.
### Embed videos
......@@ -1313,11 +1313,10 @@ For videos from other sources, [link](#link-to-video) them instead.
In most cases, it is better to [link to video](#link-to-video) instead, because
an embed takes up a lot of space on the page and can be distracting to readers.
To embed a video, follow the instructions below and make sure you have your MR
reviewed and approved by a technical writer.
To embed a video:
1. Copy the code below and paste it into your Markdown file. Leave a blank line
above and below it. Do *not* edit the code (don't remove or add any spaces).
1. Copy the code from this procedure and paste it into your Markdown file. Leave a
blank line above and below it. Do _not_ edit the code (don't remove or add any spaces).
1. In YouTube, visit the video URL you want to display. Copy the regular URL
from your browser (`https://www.youtube.com/watch?v=VIDEO-ID`) and replace
the video title and link in the line under `<div class="video-fallback">`.
......@@ -1362,8 +1361,8 @@ the documentation site, but will be displayed on GitLab's `/help`.
For example, `.gitlab-ci.yml`, `git add .`, `CODEOWNERS`, or `only: [master]`.
File names, commands, entries, and anything that refers to code should be
added to code blocks. To make things easier for the user, always add a full
code block for things that can be useful to copy and paste, as they can easily
do it with the button on code blocks.
code block for things that can be useful to copy and paste, as they can do it
with the button on code blocks.
- HTTP methods (`HTTP POST`) and HTTP status codes, both full (`404 File Not Found`)
and abbreviated (`404`), should be wrapped in inline code blocks when used in sentences.
For example: Send a `DELETE` request to delete the runner. Send a `POST` request to create one.
......@@ -1504,8 +1503,7 @@ won't render correctly. For multiple lines, use [blockquotes](#blockquotes)
instead.
Alert boxes render only on the GitLab documentation site (<https://docs.gitlab.com>).
Within GitLab itself, they will appear as plain Markdown text (like the examples
above the rendered versions, below).
In the GitLab product help, alert boxes appear as plain Markdown text.
These alert boxes are used in the GitLab documentation. These aren't strict
guidelines, but for consistency you should try to use these values:
......@@ -1519,7 +1517,7 @@ guidelines, but for consistency you should try to use these values:
### Note
Notes indicate additional information that is of special use to the reader.
Notes indicate additional information that's of special use to the reader.
Notes are most effective when used _sparingly_.
Try to avoid them. Too many notes can impact the scannability of a topic and
......@@ -1625,11 +1623,11 @@ Merge requests allow you to exchange changes you made to source code and
collaborate with other people on the same project. You'll see this term used in
the following ways:
- Use lowercase *merge requests* regardless of whether referring to the feature
- Use lowercase _merge requests_ regardless of whether referring to the feature
or individual merge requests.
As noted in the GitLab [Writing Style Guidelines](https://about.gitlab.com/handbook/communication/#writing-style-guidelines),
if you use the **MR** acronym, expand it at least once per document page.
if you use the _MR_ acronym, expand it at least once per document page.
Typically, the first use would be phrased as _merge request (MR)_ with subsequent
instances being _MR_.
......@@ -1656,15 +1654,15 @@ elements:
| Recommended | Used for | Replaces |
|:--------------------|:--------------------------------------|:---------------------------|
| *select* | buttons, links, menu items, dropdowns | "click, "press," "hit" |
| *select* or *clear* | checkboxes | "enable", "click", "press" |
| *expand* | expandable sections | "open" |
| _select_ | buttons, links, menu items, dropdowns | "click, "press," "hit" |
| _select_ or _clear_ | checkboxes | "enable", "click", "press" |
| _expand_ | expandable sections | "open" |
### Other Verbs
| Recommended | Used for | Replaces |
|:------------|:--------------------------------|:----------------------|
| *go to* | making a browser go to location | "navigate to", "open" |
| _go to_ | making a browser go to location | "navigate to", "open" |
## GitLab versions and tiers
......@@ -1695,7 +1693,7 @@ following the heading for the section. To render correctly, it must be on its
own line and surrounded by blank lines.
- For features that need to declare the GitLab version that the feature was
introduced. Text similar to the following should be added immediately below
introduced. Text similar to the following should be added immediately following
the heading as a blockquote:
- `> Introduced in GitLab 11.3.`.
......@@ -1754,7 +1752,7 @@ If applicable, include the paid tier: `([introduced/deprecated](<link-to-issue>)
Including the issue link is encouraged, but isn't a requirement. For example:
```markdown
The voting strategy (introduced in GitLab 13.4) requires
The voting strategy (in GitLab 13.4 and later) requires
the primary and secondary voters to agree.
```
......@@ -1762,22 +1760,22 @@ the primary and secondary voters to agree.
When describing functionality available in past or future versions, use:
- *Earlier*, and not *older* or *before*.
- *Later*, and not *newer* or *after*.
- _Earlier_, and not _older_ or _before_.
- _Later_, and not _newer_ or _after_.
For example:
- Available in GitLab 12.3 and earlier.
- Available in GitLab 12.4 and later.
- If using GitLab 11.4 or earlier, ...
- If using GitLab 10.6 or later, ...
- In GitLab 11.4 and earlier, ...
- In GitLab 10.6 and later, ...
### Importance of referencing GitLab versions and tiers
Mentioning GitLab versions and tiers is important to all users and contributors
to quickly have access to the issue or merge request that introduced the change
for reference. Also, they can easily understand what features they have in their
GitLab instance and version, given that the note has some key information.
to quickly have access to the issue or merge request that introduced the change.
Also, they can know what features they have in their GitLab
instance and version, given that the note has some key information.
`[Introduced](link-to-issue) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.7`
links to the issue that introduced the feature, says which GitLab tier it
......@@ -1818,7 +1816,7 @@ lines with an inserted line break. Splitting product or feature names across
lines makes searching for these items more difficult, and can cause problems if
names change.
For example, the following Markdown content is *not* formatted correctly:
For example, the following Markdown content is _not_ formatted correctly:
```markdown
When entering a product or feature name that includes a space (such as GitLab
......@@ -1843,14 +1841,14 @@ header or other page element according to the feature's availability:
| GitLab Starter and GitLab.com Bronze, and their higher tiers | `**(STARTER)**` |
| GitLab Premium and GitLab.com Silver, and their higher tiers | `**(PREMIUM)**` |
| GitLab Ultimate and GitLab.com Gold | `**(ULTIMATE)**` |
| *Only* GitLab Core and higher tiers (no GitLab.com-based tiers) | `**(CORE ONLY)**` |
| *Only* GitLab Starter and higher tiers (no GitLab.com-based tiers) | `**(STARTER ONLY)**` |
| *Only* GitLab Premium and higher tiers (no GitLab.com-based tiers) | `**(PREMIUM ONLY)**` |
| *Only* GitLab Ultimate (no GitLab.com-based tiers) | `**(ULTIMATE ONLY)**` |
| *Only* GitLab.com Free and higher tiers (no self-managed instances) | `**(FREE ONLY)**` |
| *Only* GitLab.com Bronze and higher tiers (no self-managed instances) | `**(BRONZE ONLY)**` |
| *Only* GitLab.com Silver and higher tiers (no self-managed instances) | `**(SILVER ONLY)**` |
| *Only* GitLab.com Gold (no self-managed instances) | `**(GOLD ONLY)**` |
| _Only_ GitLab Core and higher tiers (no GitLab.com-based tiers) | `**(CORE ONLY)**` |
| _Only_ GitLab Starter and higher tiers (no GitLab.com-based tiers) | `**(STARTER ONLY)**` |
| _Only_ GitLab Premium and higher tiers (no GitLab.com-based tiers) | `**(PREMIUM ONLY)**` |
| _Only_ GitLab Ultimate (no GitLab.com-based tiers) | `**(ULTIMATE ONLY)**` |
| _Only_ GitLab.com Free and higher tiers (no self-managed instances) | `**(FREE ONLY)**` |
| _Only_ GitLab.com Bronze and higher tiers (no self-managed instances) | `**(BRONZE ONLY)**` |
| _Only_ GitLab.com Silver and higher tiers (no self-managed instances) | `**(SILVER ONLY)**` |
| _Only_ GitLab.com Gold (no self-managed instances) | `**(GOLD ONLY)**` |
For clarity, all page title headers (H1s) must be have a tier markup for the
lowest tier that has information on the documentation page.
......@@ -1877,12 +1875,12 @@ For example:
Introduced by [!244](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/244),
the special markup `**(STARTER)**` will generate a `span` element to trigger the
badges and tooltips (`<span class="badge-trigger starter">`). When the keyword
*only* is added, the corresponding GitLab.com badge will not be displayed.
_only_ is added, the corresponding GitLab.com badge will not be displayed.
## Specific sections
Certain styles should be applied to specific sections. Styles for specific
sections are outlined below.
sections are outlined in this section.
### GitLab restart
......@@ -1915,17 +1913,16 @@ of the Ruby website).
GitLab currently officially supports two installation methods: installations
from source and Omnibus packages installations.
Whenever there is a setting that is configurable for both installation methods,
prefer to document it in the CE documentation to avoid duplication.
Whenever there's a setting that's configurable for both installation methods,
the preference is to document it in the CE documentation to avoid duplication.
Configuration settings include:
1. Settings that touch configuration files in `config/`.
1. NGINX settings and settings in `lib/support/` in general.
- Settings that touch configuration files in `config/`.
- NGINX settings and settings in `lib/support/` in general.
When there is a list of steps to perform, usually that entails editing the
configuration file and reconfiguring/restarting GitLab. In such case, follow
the style below as a guide:
When you document a list of steps, it may entail editing the configuration file
and reconfiguring or restarting GitLab. In that case, use these styles:
````markdown
**For Omnibus installations**
......@@ -1977,8 +1974,8 @@ can facilitate this by making sure the troubleshooting content addresses:
If the contents of each category can be summarized in one line and a list of
steps aren't required, consider setting up a [table](#tables) with headers of
*Problem* \| *Cause* \| *Solution* (or *Workaround* if the fix is temporary), or
*Error message* \| *Solution*.
_Problem_ \| _Cause_ \| _Solution_ (or _Workaround_ if the fix is temporary), or
_Error message_ \| _Solution_.
## Feature flags
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7