docs: cleanup tasks/mojos usage documentation (#1766)

Author: dariuszkuc

website/docs/plugins/gradle-plugin-usage-client.mdx

@@ -7,6 +7,9 @@ sidebar_label: Generating Client
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
+GraphQL Kotlin plugins can be used to generate a lightweight type-safe GraphQL HTTP clients. See examples below for more
+information about the client generating tasks.
+
 ## Downloading Schema SDL
 
 GraphQL endpoints are often public and as such many servers might disable introspection queries in production environment.

website/docs/plugins/gradle-plugin-usage-sdl.mdx

@@ -7,7 +7,11 @@ sidebar_label: Generating SDL
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
-## Generating SDL Example
+GraphQL Kotlin follows a code-first approach where schema is auto generated from your source code at runtime. GraphQL Kotlin
+plugins can be used to generate schema as a build time artifact. This allows you to seamlessly integrate with various
+GraphQL tools that may require a schema artifact as an input (e.g. to perform backwards compatibility checks, etc).
+
+## Generating SDL
 
 GraphQL schema can be generated directly from your source code using reflections. `graphqlGenerateSDL` will scan your
 classpath looking for classes implementing `Query`, `Mutation` and `Subscription` marker interfaces and then generates the
@@ -76,7 +80,7 @@ This task does not automatically configure itself to be part of your build lifec
 invoke it OR configure it as a dependency of some other task.
 :::
 
-## Generating SDL with Custom Hooks Provider Example
+## Using Custom Hooks Provider
 
 Plugin will default to use `NoopSchemaGeneratorHooks` to generate target GraphQL schema. If your project uses custom hooks
 or needs to generate the federated GraphQL schema, you will need to provide an instance of `SchemaGeneratorHooksProvider`

website/docs/plugins/maven-plugin-usage-client.md

@@ -4,6 +4,9 @@ title: Maven Plugin Client Usage
 sidebar_label: Generating Client
 ---
 
+GraphQL Kotlin plugins can be used to generate a lightweight type-safe GraphQL HTTP clients. See examples below for more
+information about the client generating tasks.
+
 ## Downloading Schema SDL
 
 Download SDL Mojo requires target GraphQL server `endpoint` to be specified. Task can be executed directly from the
@@ -451,71 +454,3 @@ different endpoints.
     </executions>
 </plugin>
 ```
-
-## Generating SDL Example
-
-GraphQL schema can be generated directly from your source code using reflections. `generate-sdl` mojo will scan your
-classpath looking for classes implementing `Query`, `Mutation` and `Subscription` marker interfaces and then generates the
-corresponding GraphQL schema using `graphql-kotlin-schema-generator` and default `NoopSchemaGeneratorHooks`. In order to
-limit the amount of packages to scan, this mojo requires users to provide a list of `packages` that can contain GraphQL
-types.
-
-```xml
-<plugin>
-    <groupId>com.expediagroup</groupId>
-    <artifactId>graphql-kotlin-maven-plugin</artifactId>
-    <version>${graphql-kotlin.version}</version>
-    <executions>
-        <execution>
-            <goals>
-                <goal>generate-sdl</goal>
-            </goals>
-            <configuration>
-                <packages>
-                    <package>com.example</package>
-                </packages>
-            </configuration>
-        </execution>
-    </executions>
-</plugin>
-```
-
-## Generating SDL with Custom Hooks Provider Example
-
-Plugin will default to use `NoopSchemaGeneratorHooks` to generate target GraphQL schema. If your project uses custom hooks
-or needs to generate the federated GraphQL schema, you will need to provide an instance of `SchemaGeneratorHooksProvider`
-service provider that will be used to create an instance of your custom hooks.
-
-`generate-sdl` mojo utilizes [ServiceLoader](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/ServiceLoader.html)
-mechanism to dynamically load available `SchemaGeneratorHooksProvider` service providers from the classpath. Service provider
-can be provided as part of your project, included in one of your project dependencies or through explicitly provided artifact.
-See [Schema Generator Hooks Provider](./hooks-provider.mdx) for additional details on how to create custom hooks service provider.
-Configuration below shows how to configure GraphQL Kotlin plugin with explicitly provided artifact to generate federated
-GraphQL schema.
-
-```xml
-<plugin>
-    <groupId>com.expediagroup</groupId>
-    <artifactId>graphql-kotlin-maven-plugin</artifactId>
-    <version>${graphql-kotlin.version}</version>
-    <executions>
-        <execution>
-            <goals>
-                <goal>generate-sdl</goal>
-            </goals>
-            <configuration>
-                <packages>
-                    <package>com.example</package>
-                </packages>
-            </configuration>
-        </execution>
-    </executions>
-    <dependencies>
-        <dependency>
-            <groupId>com.expediagroup</groupId>
-            <artifactId>graphql-kotlin-federated-hooks-provider</artifactId>
-            <version>${graphql-kotlin.version}</version>
-        </dependency>
-    </dependencies>
-</plugin>
-```

website/docs/plugins/maven-plugin-usage-sdl.md

@@ -4,7 +4,11 @@ title: Maven Plugin SDL Usage
 sidebar_label: Generating SDL
 ---
 
-## Generating SDL Example
+GraphQL Kotlin follows a code-first approach where schema is auto generated from your source code at runtime. GraphQL Kotlin
+plugins can be used to generate schema as a build time artifact. This allows you to seamlessly integrate with various
+GraphQL tools that may require a schema artifact as an input (e.g. to perform backwards compatibility checks, etc).
+
+## Generating SDL
 
 GraphQL schema can be generated directly from your source code using reflections. `generate-sdl` mojo will scan your
 classpath looking for classes implementing `Query`, `Mutation` and `Subscription` marker interfaces and then generates the
@@ -32,7 +36,7 @@ types.
 </plugin>
 ```
 
-## Generating SDL with Custom Hooks Provider Example
+## Using Custom Hooks Provider
 
 Plugin will default to use `NoopSchemaGeneratorHooks` to generate target GraphQL schema. If your project uses custom hooks
 or needs to generate the federated GraphQL schema, you will need to provide an instance of `SchemaGeneratorHooksProvider`