GitLab Instructions for Write The Docs Writing Day participants
Issue Description
This issue is aimed at participants in the GitLab Writing Day session (May 7) at the Write The Docs Portland 2023 conference. This will be an afternoon only session starting at 1:30pm PT.
Benefits:
- Contribute to the GitLab open source project
- Learn more about git (and GitLab)
- Learn about Vale, the popular syntax-aware linter
Knowledge of Git is not required. GitLab includes a web-based interface to edit our documentation. For more information, watch this video. To go straight to the demo (< 8 minutes), skip to the 8:03 mark.
The video is in three sections:
Help:
During Writing Day, one or more GitLab team members are available for assistance at the Writing Day table. You can also ping one of the following GitLab team members in the Write The Docs slack:
- in-person:
@AmyQ
,@arty-chan
- online only:
@evan.read
,@Russell
Key links:
- GitLab documentation
-
GitLab git repository
- With an account, you're welcome to fork and clone the repository.
- If you don't understand the meanings of "clone" and "fork," don't worry! There are other editing methods.
- GitLab documentation style guide
Process:
If you're participating in our Writing Day session, here's what we'd like you to do:
- Register for a GitLab account at https://gitlab.com/users/sign_in.
- Ask someone from GitLab to add you to https://gitlab.com/gitlab-community/community-members as a Developer.
- Review our list of Quick win issues. Let us know that you'd like to work on it, and give us your username so we can assign it to you. Assignment will let others know that you plan to work on the issue.
- Alternatively, if there's no issue you're interested in, you can make a merge request to update anything in the documentation to fit our style guide. One way to do that is fix Vale warnings in the documentation.
- Alternatively, see the first row, or pick a row from the spreadsheet. Fill in the filename if needed on a new row, and add your name next to the one you're doing.
- Go to the GitLab community fork
- Optional. You can either "Clone" the repository to edit it locally.
- Find the markdown page by going to the docs directory and finding the file related to the issue. If you know Git, you can make your changes and open a merge request. If not, never fear! Just follow these steps:
- In the top right, select Edit and make the changes to the markdown file.
- Change the "Target branch" name:
docs-wtd-1234
(replacing 1234 with the issue number) ordocs-wtd-yourname
if no issue number - For the commit message, use 3-5 words, start with a capital letter, and do not end with a period.
- Select Commit changes. A merge request opens.
- In the merge request:
- For the source branch, use the branch you just made. The target branch is in the master branch in the main GitLab repo
gitlab-org/gitlab:master
. - Select the Documentation template. In the description:
- Write a brief summary of the changes.
- After the summary, insert the blurb below (make sure to remove the backticks around it.
- For the source branch, use the branch you just made. The target branch is in the master branch in the main GitLab repo
Part of Write the Docs 2023 Writing Day
Related to: https://gitlab.com/gitlab-org/technical-writing/-/issues/789
Closes <replace this with issue link, if applicable>
/label ~documentation ~docs-only ~"Community contribution" ~"type::maintenance" ~"docs::improvement"
<!-- If this is your first contribution to GitLab, include the following, otherwise remove this and the line underneath -->
/label ~"1st contribution"
In the Writing Day session, let us know that you opened a merge request.
Fix Vale warnings
We have several tests we run on GitLab documentation.
You can learn more about Vale and documentation linting by helping us fix docs-technical-debt shown as Vale warnings.
Prerequisites:
- Knowledge of the command line.
- Git.
To find Vale warnings to fix:
-
Install Vale on your local computer.
-
Optional. If you're working on changes locally, rather than using GitLab UI, configure your editor for Vale.
-
In the command line, go to directory of the checkout of the
gitlab
project. -
Run the following command:
vale --minAlertLevel warning <path_to_markdown_file>
-
If you find a file with no warnings, try a different file.
Examples
To find all the warnings for the file doc/administration/job_logs.md
, run:
vale --minAlertLevel warning doc/administration/job_logs.md
To find all the warnings for all the files in the doc/administration/auth/
directory, run:
vale --minAlertLevel warning doc/administration/auth/*.md
To find all the warnings for all the files in the doc/administration/auth/
directory and all of its subdirectories, run:
vale --minAlertLevel warning doc/administration/auth/**/*.md
Congrats on your first MR
If this is your first merge request to the GitLab project, once your MR is merged, you can fill in our first MR swag request form.