Further refinements to the page

1 files changed, 25 insertions, 62 deletions

diff --git a/doc/development/documentation/structure.md b/doc/development/documentation/structure.md
index 54534ca3134..f10b7205a86 100644
--- a/doc/development/documentation/structure.md
+++ b/doc/development/documentation/structure.md
@@ -16,72 +16,24 @@ and the section on Content in the [Style Guide](styleguide.md).
 Most pages will be dedicated to a specifig GitLab feature or to a use case that involves
 one or more features and/or third-party tools.
 
-Every feature or use case document should include the following content in the following sequence.:
+Every feature or use case document should include the following content in the following sequence:
 
 - **Title**: Top-level heading with the feature name, or a use case name, which would start with
 a verb, like Configuring, Enabling, etc.
 - **Introduction**: A couple sentences about the subject matter and what's to be found on this page.
 - **Overview** Describe what it is, what it does, and in what context it should be used.
 - **Use cases**: describes real use case scenarios for that feature/configuration.
-- **Requirements**: describes what software and/or configuration is required to be able to
-  use the feature and, if applicable, prerequisite knowledge for being able to follow/implement the tutorial.
-  For example, familiarity with GitLab CI/CD, an account on a third-party service, dependencies installed, etc.
-  Link each one to its most relevant resource; i.e., where the reader can go to begin to fullfil that requirement.
-  (Another doc page, a third party application's site, etc.)
-- **Instructions**: clearly describes the steps to follow, leaving no gaps.
-- **Troubleshooting** guide (recommended but not required): if you know beforehand what issues
-  one might have when setting it up, or when something is changed, or on upgrading, it's
-  important to describe those too. Think of things that may go wrong and include them in the
-  docs. This is important to minimize requests for support, and to avoid doc comments with
-  questions that you know someone might ask. Answering them beforehand only makes your
-  document better and more approachable.
-
-For additional details, see the subsections below, as well as the [Documentation template for new docs](#Documentation-template-for-new-docs).
-
-### Feature overview and use cases
-
-Every major feature (regardless if present in GitLab Community or Enterprise editions)
-should present, at the beginning of the document, two main sections: **overview** and
-**use cases**. Every GitLab EE-only feature should also contain these sections.
-
-**Overview**: as the name suggests, the goal here is to provide an overview of the feature.
-Describe what it is, what it does, why it is important/cool/nice-to-have,
-what problem it solves, and what you can do with this feature that you couldn't
-do before.
-
-**Use cases**: provide at least two, ideally three, use cases for every major feature.
-You should answer this question: what can you do with this feature/change? Use cases
-are examples of how this feature or change can be used in real life.
-
-Examples:
+- **Requirements**: describes what software, configuration, account, or knowledge is required.
+- **Instructions**: One or more sets of detailed instructions to follow.
+- **Troubleshooting** guide (recommended but not required).
 
-- CE and EE: [Issues](../../user/project/issues/index.md#use-cases)
-- CE and EE: [Merge Requests](../../user/project/merge_requests/index.md)
-- EE-only: [Geo](https://docs.gitlab.com/ee/administration/geo/replication/index.html)
-- EE-only: [Jenkins integration](https://docs.gitlab.com/ee/integration/jenkins.html)
-
-Note that if you don't have anything to add between the doc title (`<h1>`) and
-the header `## Overview`, you can omit the header, but keep the content of the
-overview there.
-
-> **Overview** and **use cases** are required to **every** Enterprise Edition feature,
-and for every **major** feature present in Community Edition.
-
-### Discoverability
+For additional details on each, see the [template for new docs](#template-for-new-docs),
+below.
 
-Your new document will be discoverable by the user only if:
+Note that you can include additional subsections, as appropriate, such as 'How it Works', 'Architecture',
+and other logicial divisions such as pre- and post-deployment steps.
 
-- Crosslinked from the higher-level index (e.g., Issue Boards docs
-  should be linked from Issues; Prometheus docs should be linked from
-  Monitoring; CI/CD tutorials should be linked from CI/CD examples).
-  - When referencing other GitLab products and features, link to their
-  respective docs; when referencing third-party products or technologies,
-  link out to their external sites, documentation, and resources.
-- The headings are clear. E.g., "App testing" is a bad heading, "Testing
-  an application with GitLab CI/CD" is much better. Think of something
-  someone will search for and use these keywords in the headings.
-
-## Documentation template for new docs
+## Template for new docs
 
 To start a new document, respect the file tree and file name guidelines,
 as well as the style guidelines. Use the following template:
@@ -101,7 +53,7 @@ description: "Short document description." # Up to ~200 chars long. They will be
 > [Introduced](link_to_issue_or_mr) in GitLab (Tier) X.Y (2).
 
 An introduction -- without its own additional header -- goes here.
-Offer a short description of the feature or use case, and what to expect on this page.
+Offer a very short description of the feature or use case, and what to expect on this page.
 (You can reuse this content, or part of it, for the front matter's `description` at the top of this file).
 
 ## Overview
@@ -119,7 +71,13 @@ The feature overview should answer the following questions:
 Describe some use cases, typically in bulleted form. Include real-life examples for each.
 
 If the page itself is dedicated to a use case, this section can usually include more specific scenarios
-for use, but if that's not applicable, the section can be omitted.
+for use (e.g. variations on the main use case), but if that's not applicable, the section can be omitted.
+
+Examples of use cases on feature pages:
+- CE and EE: [Issues](../../user/project/issues/index.md#use-cases)
+- CE and EE: [Merge Requests](../../user/project/merge_requests/index.md)
+- EE-only: [Geo](https://docs.gitlab.com/ee/administration/geo/replication/index.html)
+- EE-only: [Jenkins integration](https://docs.gitlab.com/ee/integration/jenkins.html)
 
 ## Requirements
 
@@ -148,10 +106,15 @@ is simple and the document is short.
 
 <!-- ## Troubleshooting
 
-Include any troubleshooting steps that you can foresee.
-Each scenario can be a third-level heading, e.g. ### Getting error message X
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
 If you have none to add when creating a doc, leave this section in place
-but commented out, to help encourage others to add to it in the future. -->
+but commented out to help encourage others to add to it in the future. -->
 
 ---