Skip to content

Review Handbook page: /ee/install/requirements.html

The following page needs a docs review:

In your review, you should focus on the following:

  • Validate Technical accuracy
    • Run the commands as presented. Are they working? Are they formatted correctly? Are they possibly outdated? (Have we built a new method? Or for example are we using a legacy tool like ifconfig vs. ip addr) If you are unsure, you are the DRI who is responsible for figuring out who can help and getting them to help.
  • Correct Missing information from instructions
    • Are these instructions appropriate for the latest version of GitLab? If not, what caveats need to be listed?
    • Is it clear in what context that the command need to be run (root/non-root/etc)
    • Is it clear that you are in the terminal or in the ci.yaml file or where the commands/config need to be entered? Focus on determining where commands could have users asking questions and answer those questions.
  • Research any new context that came from customer scenarios
    • Search ZD for the documentation page you are reviewing or for a related topic (Reviewing a CI page, try to find CI tickets related to the content you are reviewing):
    • Were there any patterns in the questions/problems where this documentation was referenced?
    • When you find a documentation link on a ticket, you should address any follow up questions. (Example response: “Here is how to use the User API with a doc link. Next reply in the ticket from customer: it’s unclear how to filter the API results to active users.” Address this if possible in your MR. If you think it might be out of scope, ask Docs reviewer listed below for help.)
    • Link to at least 3 tickets in this issue related to the documentation page and what relevant information you gleaned from them to update our docs. For each ZD ticket you should make a comment, and add your learnings to that comment. 3 comments, one link and learning per comment.
  • Explore the issue tracker and ask fellow support engineers to see if there are known bugs or issues related to the GitLab feature you are reviewing.
    • For example, if there is a long running issue or known limitation, is that clarified in the docs? If not, add them!
    • If there are open docs issues, if you can find them, try and address in your review
    • Talk to documentation team to see if they have any context for things to be updated.
  • Perform a mechanical validation of the page: Do all of the links on the page work, internal and external links, and do they link to the appropriate pages?
    • If you are unsure of where a broken link should go, work with the documentation team for clarity, and consider asking support engineers as a backup.

What you are not responsible for

  • Stay away from splitting up pages and making new pages (suggestions welcome but new pages being created are out of scope for this assignment).
  • You do not need to review linked pages, just the content on the page assigned and that the links themselves work. Don’t worry about exact grammar; it will be addressed by tech writer and linter.

Helpful info for MR creation

The simplest way to submit a documentation update based on a review is to create an MR in the appropriate repo, and to select the Documentation template (if there is one), which will walk you through the process, and also provide links to resources you can use regarding documentation guidelines and the GitLab Style Guide. If you have questions, ask your Documentation reviewer listed below:

Edited by Katrin Leinweber