| `doc/user/` | User related documentation. Anything that can be done within the GitLab user interface goes here, including usage of the `/admin` interface. |
| `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 by using 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. Administrator settings in the GitLab user interface are under `doc/user/admin_area/`. |
| `doc/api/` | API related documentation. |
| `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/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. |
| `doc/legal/` | Legal documents about contributing to GitLab. |
| `doc/install/` | Contains instructions for installing GitLab. |
| `doc/install/` | Contains instructions for installing GitLab. |
| `doc/update/` | Contains instructions for updating GitLab. |
| `doc/update/` | Contains instructions for updating GitLab. |
| `doc/topics/` | Indexes per topic (`doc/topics/topic_name/index.md`): all resources for that topic. |
| `doc/topics/` | Indexes per topic (`doc/topics/topic_name/index.md`): all resources for that topic. |
### Work with directories and files
### Work with directories and files
...
@@ -277,10 +276,10 @@ Refer to the following items when working with directories and files:
...
@@ -277,10 +276,10 @@ Refer to the following items when working with directories and files:
Every page you would navigate under `/profile` should have its own document,
Every page you would navigate under `/profile` should have its own document,
for example, `account.md`, `applications.md`, or `emails.md`.
for example, `account.md`, `applications.md`, or `emails.md`.
-`doc/user/dashboard/` should contain all dashboard related documentation.
-`doc/user/dashboard/` should contain all dashboard related documentation.
-`doc/user/admin_area/` should contain all admin related documentation
-`doc/user/admin_area/` should contain all administrator-related
describing what can be achieved by accessing GitLab's admin interface
documentation describing what can be achieved by accessing the GitLab
(_not to be confused with `doc/administration` where server access is
administrator interface (not to be confused with `doc/administration` where
required_).
server access is required).
- 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,
own document located at `doc/user/admin_area/settings/`. For example,
the **Visibility and Access Controls** category should have a document
the **Visibility and Access Controls** category should have a document
...
@@ -567,9 +566,9 @@ tenses, words, and phrases:
...
@@ -567,9 +566,9 @@ tenses, words, and phrases:
- Avoid using the word *currently* when talking about the product or its
- Avoid using the word *currently* when talking about the product or its
features. The documentation describes the product as it is, and not as it
features. The documentation describes the product as it is, and not as it
will be at some indeterminate point in the future.
will be at some indeterminate point in the future.
- Avoid the using the word *scalability* with increasing GitLab's performance
- Avoid using the word scalability when talking about increasing GitLab
for additional users. Using the words *scale* or *scaling* in other cases is
performance for additional users. The words scale or scaling are sometimes
acceptable, but references to increasing GitLab's performance for additional
acceptable, but references to increasing GitLab performance for additional
direct readers to the GitLab [reference architectures](../../../administration/reference_architectures/index.md)
direct readers to the GitLab [reference architectures](../../../administration/reference_architectures/index.md)
for information about configuring GitLab to have the performance needed for
for information about configuring GitLab to have the performance needed for
additional users over time.
additional users over time.
- Don't use profanity or obscenities. Doing so may negatively affect other
- Don't use profanity or obscenities. Doing so may negatively affect other users
users and contributors, which is contrary to GitLab's value of
and contributors, which is contrary to the GitLab value of
[Diversity, Inclusion, and Belonging](https://about.gitlab.com/handbook/values/#diversity-inclusion).
[Diversity, Inclusion, and Belonging](https://about.gitlab.com/handbook/values/#diversity-inclusion).
- Avoid the use of [racially-insensitive terminology or phrases](https://www.marketplace.org/2020/06/17/tech-companies-update-language-to-avoid-offensive-terms/). For example:
- Avoid the use of [racially-insensitive terminology or phrases](https://www.marketplace.org/2020/06/17/tech-companies-update-language-to-avoid-offensive-terms/). For example:
- Use *primary* and *secondary* for database and server relationships.
- Use *primary* and *secondary* for database and server relationships.
...
@@ -982,9 +981,9 @@ Important:
...
@@ -982,9 +981,9 @@ Important:
tutorials, presentations, StackOverflow posts, and other sources.
tutorials, presentations, StackOverflow posts, and other sources.
- Do not link to `h1` headings.
- Do not link to `h1` headings.
Note that, with Kramdown, it is possible to add a custom ID to an HTML element
Note that with Kramdown, it's 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 don't work in `/help`. Because of this, don't use
do not use this option until further notice.
this option.
## Links
## Links
...
@@ -1268,7 +1267,7 @@ request.
...
@@ -1268,7 +1267,7 @@ request.
## Videos
## Videos
Adding GitLab's existing YouTube video tutorials to the documentation is highly
Adding GitLab YouTube video tutorials to the documentation is highly
encouraged, unless the video is outdated. Videos should not replace
encouraged, unless the video is outdated. Videos should not replace
documentation, but complement or illustrate it. If content in a video is
documentation, but complement or illustrate it. If content in a video is
fundamental to a feature and its key use cases, but this is not adequately
fundamental to a feature and its key use cases, but this is not adequately
...
@@ -1297,7 +1296,7 @@ You can link any up-to-date video that's useful to the GitLab user.
...
@@ -1297,7 +1296,7 @@ You can link any up-to-date video that's useful to the GitLab user.
The [GitLab documentation site](https://docs.gitlab.com) supports embedded
The [GitLab documentation site](https://docs.gitlab.com) supports embedded
videos.
videos.
You can only embed videos from [GitLab's official YouTube account](https://www.youtube.com/channel/UCnMGQ8QHMAnVIsI3xJrihhg).
You can embed videos from [the official YouTube account for GitLab](https://www.youtube.com/channel/UCnMGQ8QHMAnVIsI3xJrihhg) only.
For videos from other sources, [link](#link-to-video) them instead.
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
In most cases, it is better to [link to video](#link-to-video) instead, because
...
@@ -1341,9 +1340,9 @@ This is how it renders on the GitLab documentation site:
...
@@ -1341,9 +1340,9 @@ This is how it renders on the GitLab documentation site:
> - The `figure` tag is required for semantic SEO and the `video_container`
> - The `figure` tag is required for semantic SEO and the `video_container`
class is necessary to make sure the video is responsive and displays on
class is necessary to make sure the video is responsive and displays on
different mobile devices.
different mobile devices.
> - The `<div class="video-fallback">` is a fallback necessary for GitLab's
> - The `<div class="video-fallback">` is a fallback necessary for
`/help`, as GitLab's Markdown processor does not support iframes. It's hidden on
`/help`, because the GitLab Markdown processor doesn't support iframes. It's
the documentation site, but will be displayed on GitLab's`/help`.
hidden on the documentation site, but is displayed by`/help`.
## Code blocks
## Code blocks
...
@@ -1659,8 +1658,8 @@ elements:
...
@@ -1659,8 +1658,8 @@ elements:
To help users be aware of recent product improvements or additions, we add
To help users be aware of recent product improvements or additions, we add
GitLab version information to our documentation.
GitLab version information to our documentation.
The GitLab Technical Writing team determines which versions of GitLab's
The GitLab Technical Writing team determines which versions of
documentation to display on this site based on GitLab's
documentation to display on this site based on the GitLab
[Statement of Support](https://about.gitlab.com/support/statement-of-support.html#we-support-the-current-major-version-and-the-two-previous-major-versions).
[Statement of Support](https://about.gitlab.com/support/statement-of-support.html#we-support-the-current-major-version-and-the-two-previous-major-versions).
