docs: update devtools docs

Author: kamilmysliwiec

content/devtools/ci-cd.md

@@ -51,6 +51,10 @@ To see reports, navigate to the project's corresponding page (see organizations)
 
 <figure><img src="/assets/devtools/report.png" /></figure>
 
+This is particularly helpful in identifying changes that may have gone unnoticed during code reviews. For instance, let's say someone has changed the scope of a **deeply nested provider**. This change might not be immediately obvious to the reviewer, but with Devtools, we can easily spot such changes and make sure that they're intentional. Or if we remove a guard from a specific endpoint, it will show up as affected in the report. Now if we didn't have integration or e2e tests for that route, we might not notice that it's no longer protected, and by the time we do, it could be too late.
+
+Similarly, if we're working on a **large codebase** and we modify a module to be global, we'll see how many edges were added to the graph, and this - in most cases - is a sign that we're doing something wrong.
+
 #### Build preview
 
 For every published graph we can go back in time and preview how it looked before by clicking at the **Preview** button. Furthermore, if the report was generated, we should see the differences higlighted on our graph:
@@ -63,6 +67,8 @@ See screenshot below:
 
 <figure><img src="/assets/devtools/nodes-selection.png" /></figure>
 
+The ability to go back in time lets you investigate and troubleshoot the issue by comparing the current graph with the previous one. Depending on how you set things up, every pull request (or even every commit) will have a corresponding snapshot in the registry, so you can easily go back in time and see what changed. Think of Devtools as a Git but with an understanding of how Nest constructs your application graph, and with the ability to **visualize** it.
+
 #### Integrations: Github Actions
 
 First let's start from creating a new Github workflow in the `.github/workflows` directory in our project and call it, for example, `publish-graph.yml`. Inside this file, let's use the following definition:

content/devtools/overview.md

@@ -44,6 +44,8 @@ Once the `DevtoolsModule` is imported and your application is up and running (`n
 
 <figure><img src="/assets/devtools/modules-graph.png" /></figure>
 
+> info **Hint** As you can see on the screenshot above, every module connect to the `InternalCoreModule`. `InternalCoreModule` is a global module that is always imported into the root module. Since it's registered as a global node, Nest automatically creates edges between all of the modules and the `InternalCoreModule` node. Now, if you want to hide global modules from the graph, you can use the "Hide global modules" checkbox (in the sidebar).
+
 So as we can see, `DevtoolsModule` makes your application expose an additional HTTP server (on port 8000) that the Devtools application will use to introspect your app.
 
 Just to double-check that everything works as expected, change the graph view to "Classes". You should see the following screen:
@@ -56,10 +58,14 @@ To focus on a specific node, click on the rectangle and the graph will show a po
 
 <figure><img src="/assets/devtools/node-popup.png" /></figure>
 
+> info **Hint** To export a graph as an image, click on the **Export as PNG** button in the right corner of the graph.
+
 Using the form controls located in the sidebar (on the left), you can control edges proximity to, for example, visualize a specific application sub-tree:
 
 <figure><img src="/assets/devtools/subtree-view.png" /></figure>
 
+This can be particularly useful when you have **new developers** on your team and you want to show them how your application is structured. You can also use this feature to visualize a specific module (e.g. `TasksModule`) and all of its dependencies, which can come in handy when you're breaking down a large application into smaller modules (for example, individual micro-services).
+
 #### Investigating the "Cannot resolve dependency" error
 
 > info **Note** This feature is supported for `@nestjs/core` >= `v9.3.10`.
@@ -106,24 +112,46 @@ When you navigate to the **Routes explorer** page, you should see all of the reg
 
 <figure><img src="/assets/devtools/routes.png" /></figure>
 
+> info **Hint** This page shows not only HTTP routes, but also all of the other entrypoints (e.g. WebSockets, gRPC, GraphQL resolvers etc.).
+
+Entrypoints are grouped by their host controllers. You can also use the search bar to find a specific entrypoint.
+
+If you click on a specific entrypoint, **a flow graph** will be displayed. This graph shows the execution flow of the entrypoint (e.g. guards, interceptors, pipes, etc. bound to this route). This is particularly useful when you want to understand how the request/response cycle looks for a specific route, or when troubleshooting why a specific guard/interceptor/pipe is not being executed.
+
 #### Sandbox
 
 To execute JavaScript code on the fly & interact with your application in real-time, navigate to the **Sandbox** page:
 
 <figure><img src="/assets/devtools/sandbox.png" /></figure>
 
+The playground can be used to test and debug API endpoints in **real-time**, allowing developers to quickly identify and fix issues without using, for example, an HTTP client. We can also bypass the authentication layer, and so we no longer need that extra step of logging in, or even a special user account for testing purposes. For event-driven applications, we can also trigger events directly from the playground, and see how the application reacts to them.
+
+Anything that gets logged down is streamlined to the playground's console, so we can easily see what's going on.
+
+Just execute the code **on the fly** and see the results instantly, without having to rebuild the application and restart the server.
+
+<figure><img src="/assets/devtools/sandbox-table.png" /></figure>
+
+> info **Hint** To pretty display an array of objects, use the `console.table()` (or just `table()`) function.
+
 #### Bootstrap performance analyzer
 
 To see a list of all class nodes (controllers, providers, enhancers, etc.) and their corresponding instantiation times, navigate to the **Bootstrap performance** page:
 
 <figure><img src="/assets/devtools/bootstrap-performance.png" /></figure>
 
+This page is particularly useful when you want to identify the slowest parts of your application's bootstrap process (e.g. when you want to optimize the application's startup time which is crucial for, for example, serverless environments).
+
 #### Audit
 
 To see the auto-generated audit - errors/warnings/hints that the application came up with while analyzing your serialized graph, navigate to the **Audit** page:
 
 <figure><img src="/assets/devtools/audit.png" /></figure>
 
+> info **Hint** The screenshot above doesn't show all of the available audit rules.
+
+This page comes in handy when you want to identify potential issues in your application.
+
 #### Preview static files
 
 To save a serialized graph to a file, use the following code:
@@ -138,3 +166,5 @@ fs.writeFileSync('./graph.json', app.get(SerializedGraph).toString());
 Then you can drag and drop this/upload this file:
 
 <figure><img src="/assets/devtools/drag-and-drop.png" /></figure>
+
+This is helpful when you want to share your graph with someone else (e.g., co-worker), or when you want to analyze it offline.