Skip to content

Improve Requirements Management docs

Marcin Sedlak-Jakubowski requested to merge msj-reqs-better-docs into master

What does this MR do?

Avariety of improvements:

  • Change the empty state message for the Requirements page:

    • Make the sentence more focused on what the user can accomplish
    • Remove alliteration ("create criteria", or even "can create criteria")
    Before After
    image image
  • Change the page h1 from Requirements to Requirements Management to improve SEO, given that we have multiple other pages and sections called "Requirements", usually listing installation prerequisites.

  • Improve the introduction, using information from the parent epic and direction page.

    Before:

    Requirements allow you to create criteria to check your products against. They
    can be based on users, stakeholders, system, software, or anything else you
    find important to capture.

    After:

    With requirements, you can set criteria to check your products against. They can be based on users,
    stakeholders, system, software, or anything else you find important to capture.
    
    A requirement is an artifact in GitLab which describes the specific behavior of your product.
    Requirements are long-lived. They don't disappear when it's completed.
    
    If an industry standard *requires* that your application has a certain feature or behavior, you can
    [create a requirement](#create-a-requirement) to reflect this.
    When a feature is no longer necessary, you can [archive the related requirement](#archive-a-requirement).
  • Remove an unnecessary image and line ("The requirements list shows the new title immediately.")

Related issues

#212889 (closed)

Author's checklist (required)

When applicable:

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.
  3. If there has not been a technical writer review, create an issue for one using the Doc Review template.
Edited by Justin Farris

Merge request reports