feat: add documentation

docs/src/content/docs/core/immutability.mdx

@@ -1,6 +1,6 @@
 ---
 title: Immutability
-description: Learn the providers immutability
+description: Learn how immutability impacts Disco providers.
 ---
 
 import { Aside } from '@astrojs/starlight/components';
@@ -75,14 +75,17 @@ class _MainAppState extends State<MainApp> {
 The example renders `The counter is 0`. After the user presses the `FloatingActionButton`, the counter is incremented, but the UI does not update.
 This is because the provider is immutable, and the instance of the provider is not updated. In other words, the `counterProvider` is created only the first time and it still provides the initial instance.
 
-You may be sceptical about the immutability of providers, but be sure this is a nice thing.
-It helps to avoid bugs and makes the application more predictable.
+You may be skeptical about the immutability of providers, but it is actually a good thing.
+It helps avoid bugs and makes the application more predictable.
 
 The typical usage for a provider is to provide a value for a specific page or widget.
-When the Page or Widget is disposed, the provider is also disposed, and the value is no longer available.
+When the page or widget is disposed, the provider gets also disposed, and the value is no longer available.
 When the Page is opened again, a new instance of the provider is created, and the value is provided again.
 
-There is one way to force the recreation of a provider, _which I discourage_, but can be used if you know what you're doing.
+### Force the recreation of a provider
+
+There is one way to force the recreation of a provider, _which we discourage_, but can be used if you know what you are doing.
+
 ```dart {2}
 ProviderScope(
   key: ValueKey(counter),
@@ -93,7 +96,8 @@ ProviderScope(
 )
 ```
 
-This code destroys completely the widget tree and recreates it.
-The provider creation is perfomed inside the `ProviderScope` widget and causes the recreation of the provider.
-As soon as you change the key of the `ProviderScope`, the old `ProviderScope` is disposed and disposes all the providers inside it.
-Then a new `ProviderScope` is created and all the providers are created again.
+When changing a key, the widget subtree gets regenerated.
+The provider recreation is performed inside the `ProviderScope` widget. What exactly happens is the following:
+
+1. The old `ProviderScope` is disposed, which disposes of all the providers inside it.
+2. A new `ProviderScope` is created and all the providers are created again.

docs/src/content/docs/core/scoped-di.mdx

@@ -53,7 +53,7 @@ In full example below, we are going to inject the two providers above with `numb
 </Aside>
 
 <Aside>
-  Users transitioning from Provider or Riverpod should note an important distinction: this library does not include reactivity. Therefore, it does not provide equivalents to `context.watch`/`context.listen` or `ref.watch`/`ref.listen`. The only way to trigger a rebuild is by changing the key of the `ProviderScope`, which is not recommended by us. Instead, we advise injecting observables/signals directly and using their corresponding widgets or helpers to react to changes.
+  Users transitioning from Provider or Riverpod should note an important distinction: this library does not include reactivity. Therefore, it does not provide equivalents to `context.watch`/`context.listen` or `ref.watch`/`ref.listen`. The only way to trigger a rebuild is by changing the key of the `ProviderScope`, which is not recommended by us (the next section explains this in detail). Instead, we advise injecting observables/signals directly and using their corresponding widgets or helpers to react to changes.
 </Aside>
 
 ### Full example

docs/src/content/docs/examples/preferences.mdx

@@ -1,5 +1,5 @@
 ---
-title: Shared prefences example
+title: Shared preferences example
 description: An example showing how to provide async objects with Disco.
 ---
 
@@ -11,16 +11,20 @@ SharedPreferences is a package that allows you to store key-value pairs on the d
 This example shows how to provide a `SharedPreferences` object, after initialization, to the whole app using Disco.
 After the initialization, the preferences can be retrieved and updated synchronously.
 
+You can take inspiration to provide other asynchronous objects.
+
 ## Dependency
 
-This is the `shared_preferences` version used in this example:
+This is the `shared_preferences` version used in the following examples:
 
 ```yaml {2}
 dependencies:
   shared_preferences: ^2.4.0
 ```
 
-## Code
+## Example with error handling
+
+The above below handles the loading and error states of the initialization process correctly and it's the preferred way for handling async initialization in Flutter.
 
 ```dart title=main.dart
 import 'package:disco/disco.dart';
@@ -114,9 +118,10 @@ class _MyAppState extends State<MyApp> {
 }
 ```
 
-The above code handles the loading and error states of the initialization process correctly and it's the preferred way for handling async initialization in Flutter.
+## Example without error handling
 
 If you know the initialization cannot fail, or it takes just a fraction of a second and you don't want to show the loading state, you can simplify the code as follows:
+
 ```dart
 Future<void> main() async {
   WidgetsFlutterBinding.ensureInitialized();