Skip to content

Raise /gitlab-basics to SSoT Docs standards

Marcel Amirault requested to merge docs-ssot-gitlab-basics-1 into master

What does this MR do?

As part of gitlab-design#388 (closed), this brings the level of /gitlab-basics up to the SSoT standards we are aiming for within the docs project.

The /gitlab-basics docs, while useful, needed a fair amount of work to meet the standards. Many sections had no text, only code blocks, and needed some simple introductions. Other sections were not needed, or duplicated from other places. I also cut, or lengthened, lines to make it easier to edit and review in the future, and added #troubleshooting sections as needed.

I will attempt to list the important changes below to aid in reviewing:

  • gitlab-basics/add-file.md
    • Combined with add-image.
    • Add intro and bring in content from add-image, but changed for all files, not just images.
  • gitlab-basics/add-image.md
    • Combined, and redirected to, add-file
  • gitlab-basics/add-merge-request.md
    • improve intro and links
  • gitlab-basics/basic-git-commands.md
    • Fixed redirect style
  • gitlab-basics/command-line-commands.md
    • Combined all the sections with no descriptions into a table of common command line commands for faster access.
    • Sections that actually did contain details were left as they were.
    • Combined similar rm command sections together
    • Expanded section intros as needed.
  • gitlab-basics/create-branch.md
    • Improved intro and links.
  • gitlab-basics/create-project.md
    • Improve intro, and move content to section after the intro, and adjust header nesting as a result
    • Moves a note down slightly.
    • Move custom project templates up a bit.
  • gitlab-basics/create-your-ssh-keys.md
    • Improve intro and note text
  • gitlab-basics/fork-project.md
    • Remove duplicated info and link to source.
  • gitlab-basics/README.md
    • Rename ## Git basics to ## Working with Git from the command line to more accurately reflect the content
    • Remove Add an image link, as that is now combined with add-file
  • gitlab-basics/start-using-git.md
    • Diff looks ugly because it was full of very looooong lines, and even very short lines!
    • Corrects errors in the content (branch VS repo, changes VS files, for example).
    • Improves some section titles that were not accurate.
    • Adds some simplified vocabulary when new vocabulary is introduced, to make it easier to follow for beginners (this is a "basics" guide.

Related issues

Resolves https://gitlab.com/gitlab-org/gitlab-ce/issues/65153

Author's checklist

  • Follow the Documentation Guidelines and Style Guide.
  • Link docs to and from the higher-level index page, plus other related docs where helpful.
  • Apply the ~Documentation label.

Review checklist

All reviewers can help ensure accuracy, clarity, completeness, and adherence to the Documentation Guidelines and Style Guide.

1. Primary Reviewer

  • Review by a code reviewer or other selected colleague to confirm accuracy, clarity, and completeness. This can be skipped for minor fixes without substantive content changes.

2. Technical Writer

  • Optional: Technical writer review. If not requested for this MR, must be scheduled post-merge. To request for this MR, assign the writer listed for the applicable DevOps stage.

3. Maintainer

  1. Review by assigned maintainer, who can always request/require the above reviews. Maintainer's review can occur before or after a technical writer review.
  2. Ensure a release milestone is set and that you merge the equivalent EE MR before the CE MR if both exist.
  3. If there has not been a technical writer review, create an issue for one using the Doc Review template.
Edited by Marcel Amirault

Merge request reports