Merge branch 'selhorn-graphi-reo' into 'master'

Updating style for GraphQL example pages

See merge request https://gitlab.com/gitlab-org/gitlab/-/merge_requests/171041



Merged-by: Evan Read <eread@gitlab.com>
Approved-by: Evan Read <eread@gitlab.com>
Co-authored-by: Suzanne Selhorn <sselhorn@gitlab.com>

doc/api/graphql/audit_report.md

@@ -4,54 +4,27 @@ group: Compliance
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments
 ---
 
-# Set up an Audit Report with GraphQL
+# Create an audit report by using GraphQL
 
 DETAILS:
 **Tier:** Free, Premium, Ultimate
 **Offering:** GitLab.com, Self-managed, GitLab Dedicated
 
-This page describes how you can use the GraphiQL explorer to set up an audit report
-for a specific subset of users.
+You can create an audit report for a specific subset of users by using:
 
-You can run the same query directly via a HTTP endpoint, using `cURL`. For more information, see our
-guidance on getting started from the [command line](getting_started.md#command-line).
+- GraphiQL.
+- [`cURL`](getting_started.md#command-line).
 
-The [example users query](#set-up-the-graphiql-explorer) looks for a subset of users in
-a GitLab instance either by username or
-[Global ID](../../development/api_graphql_styleguide.md#global-ids).
-The query includes:
-
-- [`pageInfo`](#pageinfo)
-- [`nodes`](#nodes)
-
-## `pageInfo`
-
-This contains the data needed to implement pagination. GitLab uses cursor-based
-[pagination](getting_started.md#pagination). For more information, see
-[Pagination](https://graphql.org/learn/pagination/) in the GraphQL documentation.
-
-## `nodes`
-
-In a GraphQL query, `nodes` is used to represent a collection of [`nodes` on a graph](https://en.wikipedia.org/wiki/Vertex_(graph_theory)).
-In this case, the collection of nodes is a collection of `User` objects. For each one,
-we output:
-
-- Their user's `id`.
-- The `membership` fragment, which represents a Project or Group membership belonging
-  to that user. Outputting a fragment is denoted with the `...memberships` notation.
-
-The GitLab GraphQL API is extensive and a large amount of data for a wide variety of entities can be output.
-See the official [reference documentation](reference/index.md) for the most up-to-date information.
-
-## Set up the GraphiQL explorer
-
-This procedure presents a substantive example that you can copy and paste into GraphiQL
-explorer. GraphiQL explorer is available for:
+## Use GraphiQL
 
-- GitLab.com users at [https://gitlab.com/-/graphql-explorer](https://gitlab.com/-/graphql-explorer).
-- Self-managed users at `https://gitlab.example.com/-/graphql-explorer`.
+You can use GraphiQL to query information about a subset of users.
 
-1. Copy the following code excerpt:
+1. Open GraphiQL:
+   - For GitLab.com, use: `https://gitlab.com/-/graphql-explorer`
+   - For self-managed GitLab, use: `https://gitlab.example.com/-/graphql-explorer`
+1. Copy the following text and paste it in the left window.
+   This query searches for a subset of users by username. Alternately, you can use their
+   [Global ID](../../development/api_graphql_styleguide.md#global-ids).
 
    ```graphql
    {
@@ -103,24 +76,40 @@ explorer. GraphiQL explorer is available for:
    }
    ```
 
-1. Open the [GraphiQL explorer tool](https://gitlab.com/-/graphql-explorer).
-1. Paste the `query` listed above into the left window of your GraphiQL explorer tool.
-1. Select **Play** to get the result shown here:
-
-![GraphiQL explorer search for boards](img/user_query_example_v13_2.png)
+1. Select **Play**.
 
 NOTE:
-[The GraphQL API returns a GlobalID, rather than a standard ID.](getting_started.md#queries-and-mutations) It also expects a GlobalID as an input rather than
-a single integer.
+[The GraphQL API returns a GlobalID, rather than a standard ID](getting_started.md#queries-and-mutations).
+It also expects a GlobalID as an input rather than a single integer.
+
+This query returns the groups and projects that the user has been explicitly made a member of.
+
+- Because GraphiQL uses the session token to authorize access to resources,
+  the output is limited to the projects and groups accessible to the currently authenticated user.
+- If you are signed in as an instance administrator, you have access to all resources.
+
+The query includes:
 
-This GraphQL query returns the groups and projects that the user has been *explicitly* made a member of.
-Since the GraphiQL explorer uses the session token to authorize access to resources,
-the output is limited to the projects and groups accessible to the currently authenticated user.
+- [`pageInfo`](#pageinfo)
+- [`nodes`](#nodes)
+
+## `pageInfo`
+
+This contains the data needed to implement pagination. GitLab uses cursor-based
+[pagination](getting_started.md#pagination). For more information, see
+[Pagination](https://graphql.org/learn/pagination/) in the GraphQL documentation.
+
+## `nodes`
+
+In a GraphQL query, `nodes` represents a collection of [`nodes` on a graph](https://en.wikipedia.org/wiki/Vertex_(graph_theory)).
+In this case, the collection of nodes is a collection of `User` objects. For each one,
+the output includes:
 
-If you've signed in as an instance administrator, you would have access to all records, regardless of ownership.
+- The user's `id`.
+- The `membership` fragment, which represents project or group membership that belongs
+  to that user. Fragments are indicated by the `...memberships` notation.
 
-For more information on:
+## Related topics
 
-- GraphQL specific entities, such as Fragments and Interfaces, see the official
-  [GraphQL documentation](https://graphql.org/learn/).
-- Individual attributes, see the [GraphQL API Resources](reference/index.md).
+- [GraphQL API reference](reference/index.md)
+- [GraphQL-specific entities, like fragments and interfaces](https://graphql.org/learn/)

doc/api/graphql/branch_rules.md

@@ -4,7 +4,7 @@ group: Source Code
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments
 ---
 
-# List branch rules for a project
+# List branch rules for a project by using GraphQL
 
 DETAILS:
 **Tier:** Free, Premium, Ultimate
@@ -12,24 +12,22 @@ DETAILS:
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106954) in GitLab 15.8.
 
-This guide demonstrates how to use [GraphiQL explorer](getting_started.md#graphiql)
-to query for branch rules in a given project.
+You can query for branch rules in a given project by using:
 
-The [example query](#set-up-the-graphiql-explorer) looks for a project in a
-GitLab instance either by its full path for example `gitlab-org/gitlab-docs`.
-In the query we request all configured branch rules for a project.
+- GraphiQL.
+- [`cURL`](getting_started.md#command-line).
+- [The GitLab Development Kit (GDK)](#use-the-gdk).
 
-NOTE:
-You can run the same query directly with an HTTP endpoint, using `cURL`. For more
-information, see our guidance on getting started from the
-[command line](getting_started.md#command-line).
+## Use GraphiQL
 
-## Set up the GraphiQL explorer
+You can use GraphiQL to list the branch rules for a project.
 
-This procedure presents a substantive example that you can copy and paste into your own
-instance of the [GraphiQL explorer](https://gitlab.com/-/graphql-explorer):
-
-1. Copy the following code excerpt:
+1. Open GraphiQL:
+   - For GitLab.com, use: `https://gitlab.com/-/graphql-explorer`
+   - For self-managed GitLab, use: `https://gitlab.example.com/-/graphql-explorer`
+1. Copy the following text and paste it in the left window.
+   This query searches for a project by its full path, for example `gitlab-org/gitlab-docs`.
+   It requests all configured branch rules for the project.
 
    ```graphql
    query {
@@ -108,18 +106,14 @@ instance of the [GraphiQL explorer](https://gitlab.com/-/graphql-explorer):
    }
    ```
 
-1. Open the [GraphiQL explorer tool](https://gitlab.com/-/graphql-explorer).
-1. Paste the `query` listed above into the left window of your GraphiQL explorer tool.
-1. Select **Play** to get this result:
-
-   ![GraphiQL explorer query for branch rules](img/list_branch_rules_query_example_v15_8.png)
+1. Select **Play**.
 
-If no branch rules are displayed, it may be because:
+If no branch rules are displayed, it might be because:
 
 - No branch rules are configured.
-- Your role doesn't have permission to view branch rules. Administrators have access to all records.
+- Your role doesn't have permission to view branch rules. Administrators have access to all resources.
 
-## Run the query in the GDK
+## Use the GDK
 
 Instead of requesting access, it may be easier for you to run the query in the
 [GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit).
@@ -127,15 +121,17 @@ Instead of requesting access, it may be easier for you to run the query in the
 1. Sign in as the default admin, `root`, with the credentials from
    [the GDK documentation](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/gdk_commands.md#get-the-login-credentials).
 1. Ensure you have some branch rules configured for the `flightjs/Flight` project.
-1. Replace the full path in the query:
+1. In your GDK instance, open GraphiQL: `http://gdk.test:3000/-/graphql-explorer`.
+1. Copy the query and paste it in the left window.
+1. Replace the full path with the following path:
 
    ```graphql
    query {
      project(fullPath: "flightjs/Flight") {
    ```
 
-1. In your GDK instance, visit the GraphiQL explorer tool: `http://gdk.test:3000/-/graphql-explorer`.
-1. Paste the `query` listed above into the left window of your GraphiQL explorer tool.
-1. Select **Play** to view the result.
+1. Select **Play**.
+
+## Related topics
 
-For more information on each field, see the [GraphQL API Resources](reference/index.md).
+- [GraphQL API reference](reference/index.md)

doc/development/documentation/graphql_styleguide.md

@@ -23,54 +23,54 @@ To create a dedicated GraphQL page, create a new `.md` file in the
 `doc/api/graphql/` directory. Give the file a functional name, like
 `import_from_specific_location.md`.
 
-## Start the page with an explanation
+## Add metadata
 
-Include a page title that describes the GraphQL functionality in a few words,
-like:
+Add descriptive content and a title at the top of the page, for example:
 
 ```markdown
-# Search for [substitute kind of data]
+---
+stage: Create
+group: Source Code
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments
+---
+
+# List branch rules for a project by using GraphQL
+
+DETAILS:
+**Tier:** Free, Premium, Ultimate
+**Offering:** GitLab.com, Self-managed, GitLab Dedicated
 ```
 
-Describe the search. One sentence may be all you need. More information may
-help readers learn how to use the example for their GitLab deployments.
+For help editing this content for your use case, ask a technical writer.
 
-## Include a procedure that uses GraphiQL
+## Add content
 
-GraphiQL can help readers test queries against their working deployments.
-Create a task to help guide them.
+Now add the body text. You can use this content as a starting point
+and replace the text with your own information.
 
-- Use the following title:
+```markdown
+You can query for branch rules in a given project by using:
+
+- GraphiQL.
+- [`cURL`](getting_started.md#command-line).
 
-  ```markdown
-  ## Use GraphiQL
-  ```
+## Use GraphiQL
 
-- Include a code block with the query that anyone can include in their
-  instance of GraphiQL:
+You can use GraphiQL to list the branch rules for a project.
 
-  ````markdown
-  ```graphql
-  query {
-    <insert queries here>
-  }
-  ```
-  ````
+1. Open GraphiQL:
+   - For GitLab.com, use: `https://gitlab.com/-/graphql-explorer`
+   - For self-managed GitLab, use: `https://gitlab.example.com/-/graphql-explorer`
+1. Copy the following text and paste it in the left window.
 
-- Tell the user what to do:
+   <graphql codeblock here>
 
-  ```markdown
-  1. Open GraphiQL:
-     - For GitLab.com, use: `https://gitlab.com/-/graphql-explorer`
-     - For self-managed GitLab, use: `https://gitlab.example.com/-/graphql-explorer`
-  1. Paste the `query` listed previously into the left window of GraphiQL.
-  1. Select **Play**.
-  ```
+1. Select **Play**.
 
-- Include the results from GraphiQL.
-- Follow up with an example of what you can do with the output. Make sure the
-  example is something that readers can do on their own deployments.
-- Include a link to the [GraphQL API resources](../../api/graphql/reference/index.md).
+## Related topics:
+
+- [GraphQL API reference](reference/index.md)
+```
 
 ## Add the GraphQL example to the global navigation