diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index 698bc59a95167ec740242372acf15365bfba8428..be8494e19cd4e821160c244914a30a230a9546fe 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -10,26 +10,42 @@ 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 +## Update the documentation -You don't need an issue to update the documentation. +Prerequisites: -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). +- If you're not a GitLab team member, you must update the GitLab documentation from a fork. You can: + - [Request access to the GitLab community fork](https://gitlab.com/groups/gitlab-community/community-members/-/group_members/request_access). + - Create your own fork. Go to the [GitLab repository](https://gitlab.com/gitlab-org/gitlab) and in the upper-right corner, select **Fork**. -You can alternately: +To update the documentation: -- 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. +1. Go to the [GitLab community fork](https://gitlab.com/gitlab-community/gitlab) or your own fork. +1. 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**. + +Alternatively, if you don't want to search through the `/doc` directory, on <https://docs.gitlab.com>, at the bottom of any page, select **View page source** or **Edit in Web IDE**. +You are prompted to create a fork or switch to your fork before you can make changes. 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 +## What to work on -If you're looking for an open issue, you can +You don't need an issue to update the documentation, but if you're looking for open issues to work on, [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: @@ -41,29 +57,8 @@ When you find an issue you'd like to work on: @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**. +You can try installing and running the [Vale linting tool](testing.md#vale) +and fixing the resulting issues. ## Ask for help