Improve Requirements Management docs

doc/user/project/requirements/index.md

@@ -2,13 +2,19 @@
 type: reference, howto
 ---
 
-# Requirements **(ULTIMATE)**
+# Requirements Management **(ULTIMATE)**
 
 > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2703) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10.
 
-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.
+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 and don't disappear unless manually cleared.
+
+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).
 
 <i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
 For an overview, see [GitLab 12.10 Introduces Requirements Management](https://www.youtube.com/watch?v=uSS7oUNSEoU).
@@ -38,22 +44,18 @@ list page.
 
 To edit a requirement:
 
-1. From the requirements list, click the **Edit** (**{pencil}**) button.
+1. From the requirements list, click **Edit** (**{pencil}**).
 1. Update the title in text input field.
 1. Click **Save changes**.
 
 ![requirement edit view](img/requirement_edit_view_v12_10.png)
 
-The requirements list shows the new title immediately.
-
-![requirement edit saved](img/requirement_edit_save_v12_10.png)
-
 ## Archive a requirement
 
 You can archive an open requirement (if you have the necessary privileges) while
 you're in the **Open** tab.
 
-From the requirements list page, click the **Archive** (**{archive}**) button.
+From the requirements list page, click **Archive** (**{archive}**).
 
 ![requirement archive view](img/requirement_archive_view_v12_10.png)
 
@@ -65,6 +67,6 @@ You can view the list of archived requirements in the **Archived** tab.
 
 ![archived requirements list](img/requirements_archived_list_view_v12_10.png)
 
-To reopen an archived requirement, click the **Reopen** button.
+To reopen an archived requirement, click **Reopen**.
 
 As soon as a requirement is reopened, it no longer appears in the **Archived** tab.

ee/app/assets/javascripts/requirements/components/requirements_empty_state.vue

@@ -31,13 +31,13 @@ export default {
     emptyStateTitle() {
       return this.requirementsCount[FilterState.all]
         ? FilterStateEmptyMessage[this.filterBy]
-        : __('Requirements allow you to create criteria to check your products against.');
+        : __('With requirements, you can set criteria to check your products against.');
     },
     emptyStateDescription() {
       return !this.requirementsCount[FilterState.all]
         ? __(
-            `Requirements can be based on users, stakeholders, system, software
-             or anything else you find important to capture.`,
+            `Requirements can be based on users, stakeholders, system, software,
+            or anything else you find important to capture.`,
           )
         : null;
     },

ee/changelogs/unreleased/msj-reqs-better-docs.yml

+---
+title: Improve Requirements Management empty state
+merge_request: 30716
+author: Marcin Sedlak-Jakubowski
+type: fixed

ee/spec/frontend/requirements/components/requirements_empty_state_spec.js

@@ -64,7 +64,7 @@ describe('RequirementsEmptyState', () => {
 
       it('returns a generic string when project has no requirements', () => {
         expect(wrapper.vm.emptyStateTitle).toBe(
-          'Requirements allow you to create criteria to check your products against.',
+          'With requirements, you can set criteria to check your products against.',
         );
       });
     });
@@ -72,7 +72,7 @@ describe('RequirementsEmptyState', () => {
     describe('emptyStateDescription', () => {
       it('returns a generic string when project has no requirements', () => {
         expect(wrapper.vm.emptyStateDescription).toBe(
-          'Requirements can be based on users, stakeholders, system, software or anything else you find important to capture.',
+          'Requirements can be based on users, stakeholders, system, software, or anything else you find important to capture.',
         );
       });
 
@@ -98,7 +98,7 @@ describe('RequirementsEmptyState', () => {
 
       expect(emptyStateEl.exists()).toBe(true);
       expect(emptyStateEl.attributes('alt')).toBe(
-        'Requirements allow you to create criteria to check your products against.',
+        'With requirements, you can set criteria to check your products against.',
       );
       expect(emptyStateEl.attributes('src')).toBe(
         '/assets/illustrations/empty-state/requirements.svg',

locale/gitlab.pot

@@ -18184,10 +18184,7 @@ msgstr ""
 msgid "Requirements"
 msgstr ""
 
-msgid "Requirements allow you to create criteria to check your products against."
-msgstr ""
-
-msgid "Requirements can be based on users, stakeholders, system, software or anything else you find important to capture."
+msgid "Requirements can be based on users, stakeholders, system, software, or anything else you find important to capture."
 msgstr ""
 
 msgid "Requires approval from %{names}."
@@ -24612,6 +24609,9 @@ msgstr ""
 msgid "Will deploy to"
 msgstr ""
 
+msgid "With requirements, you can set criteria to check your products against."
+msgstr ""
+
 msgid "Withdraw Access Request"
 msgstr ""