1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
|
---
stage: none
group: Documentation Guidelines
info: For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects.
---
# Contribute to the GitLab documentation
The GitLab documentation is the single source of truth (SSOT)
for information about how to configure, use, and troubleshoot GitLab.
Everyone is welcome to contribute to the GitLab documentation.
## Work without an issue
You don't need an issue to update the documentation.
On <https://docs.gitlab.com>, at the bottom of any page,
you can select **View page source** or **Edit in Web IDE** and [get started with a merge request](#open-your-merge-request).
You can alternately:
- Choose a page [in the `/doc` directory](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc)
and edit it from there.
- Try installing and running the [Vale linting tool](testing.md#vale)
and fixing the resulting issues.
When you're developing code, the workflow for updating docs is slightly different.
For details, see the [merge request workflow](../contributing/merge_request_workflow.md).
## Search available issues
If you're looking for an open issue, you can
[review the list of documentation issues curated specifically for new contributors](https://gitlab.com/gitlab-org/gitlab/-/issues/?sort=created_date&state=opened&label_name%5B%5D=documentation&label_name%5B%5D=docs-only&label_name%5B%5D=Seeking%20community%20contributions&first_page_size=20).
When you find an issue you'd like to work on:
- If the issue is already assigned to someone, pick a different one.
- If the issue is unassigned, add a comment and ask to work on the issue. For a Hackathon, use `@docs-hackathon`. Otherwise, use `@gl-docsteam`. For example:
```plaintext
@docs-hackathon I would like to work on this issue
```
- Do not ask for more than three issues at a time.
## Open your merge request
When you are ready to update the documentation:
1. Go to the [GitLab repository](https://gitlab.com/gitlab-org/gitlab).
1. In the upper-right corner, select **Fork**. Forking makes a copy of the repository on GitLab.com.
1. In your fork, find the documentation page in the `\doc` directory.
1. If you know Git, make your changes and open a merge request.
If not, follow these steps:
1. In the upper right, select **Edit > Edit single file**.
1. Make your changes.
1. When you're ready to submit your changes, in the **Commit message** text box, enter a commit message.
Use 3-5 words, start with a capital letter, and do not end with a period.
1. Select **Commit changes**.
1. On the left sidebar, select **Code > Merge requests**.
1. Select **New merge request**.
1. For the source branch, select your fork and branch. If you did not create a branch, select `master`.
For the target branch, select the [GitLab repository](https://gitlab.com/gitlab-org/gitlab) `master` branch.
1. Select **Compare branches and continue**. A new merge request opens.
1. Select the **Documentation** template. In the description, write a brief summary of the changes and link to the related issue, if there is one.
1. Select **Create merge request**.
## Ask for help
Ask for help from the Technical Writing team if you:
- Need help to choose the correct place for documentation.
- Want to discuss a documentation idea or outline.
- Want to request any other help.
To identify someone who can help you:
1. Locate the Technical Writer for the relevant
[DevOps stage group](https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments).
1. Either:
- If urgent help is required, directly assign the Technical Writer in the issue or in the merge request.
- If non-urgent help is required, ping the Technical Writer in the issue or merge request.
If you are a member of the GitLab Slack workspace, you can request help in the `#docs` channel.
## Branch naming
The [CI/CD pipeline for the main GitLab project](../pipelines/index.md) is configured to
run shorter, faster pipelines on merge requests that contain only documentation changes.
If you submit documentation-only changes to Omnibus, Charts, or Operator,
to make the shorter pipeline run, you must follow these guidelines when naming your branch:
| Branch name | Valid example |
|:----------------------|:-----------------------------|
| Starting with `docs/` | `docs/update-api-issues` |
| Starting with `docs-` | `docs-update-api-issues` |
| Ending in `-docs` | `123-update-api-issues-docs` |
|
