Merge branch 'add-graphql-settings-style-guide' into 'master'

Add graphql howto doc to style guide

See merge request gitlab-org/gitlab!36228

doc/development/api_graphql_styleguide.md

@@ -1204,3 +1204,7 @@ See the [schema reference](../api/graphql/reference/index.md) for details.
 This generated GraphQL documentation needs to be updated when the schema changes.
 For information on generating GraphQL documentation and schema files, see
 [updating the schema documentation](rake_tasks.md#update-graphql-documentation-and-schema-definitions).
+
+To help our readers, you should also add a new page to our [GraphQL API](../api/graphql/index.md) documentation.
+For guidance, see the [GraphQL API](documentation/styleguide.md#graphql-api) section
+of our documentation style guide.

doc/development/api_styleguide.md

@@ -13,7 +13,7 @@ Always use an [Entity](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/api/
 
 ## Documentation
 
-API endpoints must come with [documentation](documentation/styleguide.md#api), unless it is internal or behind a feature flag.
+API endpoints must come with [documentation](documentation/styleguide.md#restful-api), unless it is internal or behind a feature flag.
 The docs should be in the same merge request, or, if strictly necessary,
 in a follow-up with the same milestone as the original merge request.
 

doc/development/documentation/styleguide.md

@@ -1613,10 +1613,10 @@ Learn how to [document features deployed behind flags](feature_flags.md).
 For guidance on developing GitLab with feature flags, see
 [Feature flags in development of GitLab](../feature_flags/index.md).
 
-## API
+## RESTful API
 
-Here is a list of must-have items. Use them in the exact order that appears
-on this document. Further explanation is given below.
+Here is a list of must-have items for RESTful API documentation. Use them in the
+exact order that appears on this document. Further explanation is given below.
 
 - Every method must have the REST API request. For example:
 
@@ -1807,3 +1807,80 @@ exclude specific users when requesting a list of users for a project, you would
 ```shell
 curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --data "skip_users[]=<user_id>" --data "skip_users[]=<user_id>" https://gitlab.example.com/api/v4/projects/<project_id>/users
 ```
+
+## GraphQL API
+
+GraphQL APIs are different from [RESTful APIs](#restful-api). Reference information is
+generated automatically in our [GraphQL reference](../../api/graphql/reference/index.md).
+
+However, it's helpful to include examples on how to use GraphQL for different "use cases",
+with samples that readers can use directly in the [GraphiQL explorer](../api_graphql_styleguide.md#graphiql).
+
+This section describes the steps required to add your GraphQL examples to GitLab documentation.
+
+### Add a dedicated GraphQL page
+
+To create a dedicated GraphQL page, create a new `.md` file in the `doc/api/graphql/` directory.
+Give that file a functional name, such as `import_from_specific_location.md`.
+
+### Start the page with an explanation
+
+Include a page title that describes the GraphQL functionality in a few words, such as:
+
+```markdown
+# Search for [substitute kind of data]
+```
+
+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.
+
+### Include a procedure using the GraphiQL explorer
+
+The GraphiQL explorer can help readers test queries with working deployments. Set up the section with the following:
+
+- Use the following title:
+
+  ```markdown
+  ## Set up the GraphiQL explorer
+  ```
+
+- Include a code block with the query that anyone can include in their instance of
+  the GraphiQL explorer:
+
+  ````markdown
+  ```graphql
+  query {
+    <insert queries here>
+  }
+  ```
+  ````
+
+- Tell the user what to do:
+
+  ```markdown
+  1. Open the GraphiQL explorer tool in the following URL: `https://gitlab.com/-/graphql-explorer`.
+  1. Paste the `query` listed above into the left window of your GraphiQL explorer tool.
+  1. Click Play to get the result shown here:
+  ```
+
+- Include a screenshot of the result in the GraphiQL explorer. Follow the naming
+  convention described in the [Save the image](#save-the-image) section.
+- 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).
+
+### Add the GraphQL example to the Table of Contents
+
+You'll need to open a second MR, against the [GitLab Docs repository](https://gitlab.com/gitlab-org/gitlab-docs/).
+
+We store our Table of Contents in the `default-nav.yaml` file, in the `content/_data`
+subdirectory. You can find the GraphQL section under the following line:
+
+```yaml
+      - category_title: GraphQL
+```
+
+Be aware that CI tests for that second MR will fail with a bad link until the main MR
+that adds the new GraphQL page is merged.
+
+And that's all you need!