docs: some wording updates

Author: kamilmysliwiec

content/fundamentals/discovery-service.md

@@ -1,11 +1,12 @@
-### Discovery Service
+### Discovery service
 
-The `DiscoveryService` is a utility provided by `@nestjs/core` that allows developers to dynamically discover providers, controllers, and other metadata within a NestJS application. This can be particularly useful for building plugins, decorators, or features that rely on runtime introspection.
+The `DiscoveryService` provided by the `@nestjs/core` package is a powerful utility that allows developers to dynamically inspect and retrieve providers, controllers, and other metadata within a NestJS application. This is particularly useful when building plugins, decorators, or advanced features that rely on runtime introspection. By leveraging `DiscoveryService`, developers can create more flexible and modular architectures, enabling automation and dynamic behavior in their applications.
 
-Before using the `DiscoveryService`, you need to import the `DiscoveryModule` in your module:
+#### Getting started
+
+Before using `DiscoveryService`, you need to import the `DiscoveryModule` in the module where you intend to use it. This ensures that the service is available for dependency injection. Below is an example of how to configure it within a NestJS module:
 
 ```typescript
-@@filename(example.module)
 import { Module } from '@nestjs/common';
 import { DiscoveryModule } from '@nestjs/core';
 import { ExampleService } from './example.service';
@@ -17,7 +18,7 @@ import { ExampleService } from './example.service';
 export class ExampleModule {}
 ```
 
-Then, inject `DiscoveryService` into a provider or service:
+Once the module is set up, `DiscoveryService` can be injected into any provider or service where dynamic discovery is required.
 
 ```typescript
 @@filename(example.service)
@@ -35,61 +36,64 @@ export class ExampleService {
 }
 ```
 
-> info **Hint** The `DiscoveryService` class is imported from the `@nestjs/core` package.
-
-#### Discovering Providers
+#### Discovering providers and controllers
 
-You can retrieve all registered providers in the application:
+One of the key capabilities of `DiscoveryService` is retrieving all registered providers in the application. This is useful for dynamically processing providers based on specific conditions. The following snippet demonstrates how to access all providers:
 
 ```typescript
 const providers = this.discoveryService.getProviders();
 console.log(providers);
 ```
 
-Each provider object contains information about the instance, token, and metadata.
-
-#### Discovering Controllers
-
-Retrieve all registered controllers:
+Each provider object contains information such as its instance, token, and metadata. Similarly, if you need to retrieve all registered controllers within the application, you can do so with:
 
 ```typescript
 const controllers = this.discoveryService.getControllers();
 console.log(controllers);
 ```
 
-#### Finding Metadata
+This feature is particularly beneficial for scenarios where controllers need to be processed dynamically, such as analytics tracking, or automatic registration mechanisms.
 
-`DiscoveryService` can help find metadata attached to providers or controllers. This is useful when working with decorators that add metadata. Let's see an example. Suppose you have a custom decorator that adds metadata to a provider:
+#### Extracting metadata
+
+Beyond discovering providers and controllers, `DiscoveryService` also enables retrieval of metadata attached to these components. This is particularly valuable when working with custom decorators that store metadata at runtime.
+
+For example, consider a case where a custom decorator is used to tag providers with specific metadata:
 
 ```typescript
 import { DiscoveryService } from '@nestjs/core';
 
-export const Pets = DiscoveryService.createDecorator();
+export const FeatureFlag = DiscoveryService.createDecorator();
 ```
 
-And you use it in a service:
+Applying this decorator to a service allows it to store metadata that can later be queried:
 
 ```typescript
 import { Injectable } from '@nestjs/common';
-import { Pets } from './custom-metadata.decorator';
+import { FeatureFlag } from './custom-metadata.decorator';
 
 @Injectable()
-@Pets('cats')
+@FeatureFlag('experimental')
 export class CustomService {}
 ```
 
-Now, you can use `DiscoveryService` to find all providers with this metadata:
+Once metadata is attached to providers in this way, `DiscoveryService` makes it easy to filter providers based on assigned metadata. The following code snippet demonstrates how to retrieve providers that have been tagged with a specific metadata value:
 
 ```typescript
 const providers = this.discoveryService.getProviders();
 
 const [provider] = providers.filter(
-  (prov) => this.discoveryService.getMetadataByDecorator(Pets, prov) === 'cats',
+  (item) =>
+    this.discoveryService.getMetadataByDecorator(FeatureFlag, item) ===
+    'experimental',
 );
 
-console.log('Providers with cats metadata:', provider);
+console.log(
+  'Providers with the "experimental" feature flag metadata:',
+  provider,
+);
 ```
 
-### Conclusion
+#### Conclusion
 
-`DiscoveryService` is a powerful tool for runtime introspection in NestJS applications. It allows you to discover providers, controllers, and metadata dynamically, making it useful for plugin development, custom decorators, and advanced framework-level features.
+The `DiscoveryService` is a versatile and powerful tool that enables runtime introspection in NestJS applications. By allowing dynamic discovery of providers, controllers, and metadata, it plays a crucial role in building extensible frameworks, plugins, and automation-driven features. Whether you need to scan and process providers, extract metadata for advanced processing, or create modular and scalable architectures, `DiscoveryService` provides an efficient and structured approach to achieving these goals.

src/app/homepage/menu/menu.component.ts

@@ -75,14 +75,14 @@ export class MenuComponent implements OnInit {
           title: 'Lifecycle events',
           path: '/fundamentals/lifecycle-events',
         },
-        {
-          title: 'Platform agnosticism',
-          path: '/fundamentals/platform-agnosticism',
-        },
         {
           title: 'Discovery service',
           path: '/fundamentals/discovery-service',
         },
+        {
+          title: 'Platform agnosticism',
+          path: '/fundamentals/platform-agnosticism',
+        },
         { title: 'Testing', path: '/fundamentals/testing' },
       ],
     },