Add description metadata to docs for better link previews

Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.

❗ COMMUNITY CONTRIBUTORS, PLEASE ONLY PICK UP ONE DOC/FILE TO ALLOW OTHER NEW CONTRIBUTORS TO LEARN FROM THESE TOO ❗

This issue is to improve how links to GitLab docs are previewed in Slack and other messengers.

Pages that don't have description metadata, unfurl like this:

image

We need more informative page descriptions to give people better context.

Implementation plan

To contribute to this issue:

  1. Open this spreadsheet.

  2. Put your username next to the page you want to improve.

    • All of the files are in the doc folder in the GitLab repo.
    • Assign yourself no more than 3 doc files at a time, maximum 10 total. Many people want to contribute, so we'd like everyone to have an opportunity.
    • Prioritize choosing pages with the highest Priority (1 is highest).
    • If the pages you're editing belong to the same product group (see column Group), you can include them in the same merge request.

  3. Open a merge request to add a description metadata field above the title: line.

    The description should be a summary of what the page is about and 155 to 160 characters long. Read our description metadata guidelines.

    For details with how to open a merge request, see Contribute to the GitLab documentation.

    • In the merge request description, include this text: Related to: https://gitlab.com/gitlab-org/gitlab/-/issues/525312

  4. When you're ready for review, make sure the MR title doesn't start with Draft: or WIP: and wait. GitLab Bot should assign the right person to review your changes.

    • If a couple hours pass and it hasn't happened, add a comment with @gitlab-bot ready.

Thank you in advance for your contribution!

Description examples

Examples of good descriptions:

Regenerate the page list

The list of files was collected with:

find doc/ -name "*.md" -type f -exec bash -c 'head -n 10 "$1" | grep -q "description:" || echo "$1"' _ {} \; | sort
How it works
  1. find doc/ -name "*.md" -type f - Finds all files with the .md extension in the doc directory and subdirectories.
  2. -exec bash -c '...' _ {} \; - Executes a bash command for each found file:
    1. head -n 10 "$1" - Gets the first 10 lines of each file.
    2. grep -q "description:" - Quietly searches for "description:" in those lines.
    3. || echo "$1" - If the grep command doesn't find a match (returns non-zero), it prints the filename.
  3. sort - sorts the lines alphabetically.
Edited by 🤖 GitLab Bot 🤖