diff --git a/doc/api/graphql/reference/index.md b/doc/api/graphql/reference/index.md
index 01295064525cb639a3d8a2eea2d9283f2635d073..8d7b5069dea77cbd2974dab769c5e1ee2f4f9ffd 100644
--- a/doc/api/graphql/reference/index.md
+++ b/doc/api/graphql/reference/index.md
@@ -8,6 +8,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w
   This documentation is auto generated by a script.
   Please do not edit this file directly.
 
+  To edit the introductory text, modify `tooling/graphql/docs/templates/default.md.haml`.
+
   Run `bundle exec rake gitlab:graphql:compile_docs`
   or check the `compile_docs` task in `lib/tasks/gitlab/graphql.rake`.
 -->
@@ -16,7 +18,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 This documentation is self-generated based on GitLab current GraphQL schema.
 
-The API can be explored using the [interactive GraphQL explorer](../index.md#interactive-graphql-explorer).
+The API can be explored using the [interactive GraphQL explorer](../index.md#interactive-graphql-explorer). Developers can also [generate a machine-readable GraphQL schema in IDL and JSON formats](../../../development/rake_tasks.md#update-machine-readable-schema-files).
 
 Each table below documents a GraphQL type. Types match loosely to models, but not all
 fields and methods on a model are available via GraphQL.
diff --git a/tooling/graphql/docs/helper.rb b/tooling/graphql/docs/helper.rb
index 99f689f3cb11938187b0c0da4e617b864bbea786..f17acda11f8bb035b86909e8655ccffad2e11228 100644
--- a/tooling/graphql/docs/helper.rb
+++ b/tooling/graphql/docs/helper.rb
@@ -64,6 +64,8 @@ def auto_generated_comment
               This documentation is auto generated by a script.
               Please do not edit this file directly.
 
+              To edit the introductory text, modify `tooling/graphql/docs/templates/default.md.haml`.
+
               Run `bundle exec rake gitlab:graphql:compile_docs`
               or check the `compile_docs` task in `lib/tasks/gitlab/graphql.rake`.
             -->
diff --git a/tooling/graphql/docs/templates/default.md.haml b/tooling/graphql/docs/templates/default.md.haml
index 2ff10cf29cde8a21879322732fe6f11325594ce8..46862d00b5b2383614c0c3b295d27d210311f577 100644
--- a/tooling/graphql/docs/templates/default.md.haml
+++ b/tooling/graphql/docs/templates/default.md.haml
@@ -7,7 +7,7 @@
 
   This documentation is self-generated based on GitLab current GraphQL schema.
 
-  The API can be explored using the [interactive GraphQL explorer](../index.md#interactive-graphql-explorer).
+  The API can be explored using the [interactive GraphQL explorer](../index.md#interactive-graphql-explorer). Developers can also [generate a machine-readable GraphQL schema in IDL and JSON formats](../../../development/rake_tasks.md#update-machine-readable-schema-files).
 
   Each table below documents a GraphQL type. Types match loosely to models, but not all
   fields and methods on a model are available via GraphQL.