Learning how to contribute to documentation

Familiarize yourself with how GitLab authors documentation

Read the following to become familiar with how technical writing is done at GitLab:

• Complete the GitLab Technical Writing Fundamentals course.
• Read GitLab Documentation guidelines and the various pages linked from the introduction.
• Familiarize yourself with the word list and style guide.
• Look at the gitlab project's doc directory. Each page on the docs site is in this directory. For example:

  • This page on the docs site: https://docs.gitlab.com/ee/user/project/labels.html

  • Corresponds to this page in the repo: https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/project/labels.md

    For quick access to any markdown file, when you're on the docs site, scroll to the bottom and select View page source.

• Review the GitLab docs navigation file. This file is how the left navigation on the docs site is populated.

Set up your computer

• Ensure you have Git installed and your SSH key added to GitLab.
• Install an IDE, like VS Code.
• Clone the GitLab repo to your local machine, and view the files in VS Code.
• Optional. Set up a local docs build on your machine by following these instructions.

Now you can start creating small merge requests with doc updates.

Fix these issues

Open MRs for the following words. Instructions for how to open an MR are just below.

Note: Each time you start a new MR, ensure you are in the right gitlab directory, then run git checkout master to ensure you're on the master branch, then git pull to make sure your local machine has all the latest stuff. Then you can edit the file, create the branch and follow the steps we did in zoom (listed below).

• Search for and remove the word "please" Rule here
• Search for "respectively" and re-write the phrase so each option is clearly spelled out Rule here
• Search for "as" and replace with "because" if that's how it's being used Rule here (There will be many of these, no need to try to fix all of them)
• Search for "once" and replace with "after" Rule here
• Search for "toggle" and ensure it's not being used as a verb Rule here

If you find results under /doc/development or doc/architecture/blueprints you don't need to fix. (You can, but you don't have to.)

Create a merge request (MR)

You can create an MR many different ways. Some possibilities are:

• Open a markdown file in the repo and in the top right, select Edit (to edit in the IDE or in the UI).
• Go to the page on the docs site, scroll to the bottom, and View Page Source. Then Edit in the top right.
• In your local environment, in the repo you cloned, edit the markdown file. Then:
  1. Create a branch: git checkout -b mybranchname
  2. Add the files you edited: git add .
  3. Add a commit message: git commit -m "My commit message here" (Start with a capital letter, use 3-5 words, do not end in period)
  4. Push to the repo: git push origin mybranchname
  5. After you run this command, follow the URL Git gives you to create the MR.

To get a review, ask the #docs slack channel or assign the MR to a writer by using roulette.

If you're not ready to start making merge requests, you can create a test project and use it to practice.