Documentation improvements (#1549)

* Style improvements to docs

* Edit section on read model query join keys

* More edits to section on read model query join keys

* More edits to section on read model query join keys

---------

Co-authored-by: Castro, Mario <[email protected]>

website/docs/03_architecture/06_read-model.mdx

@@ -103,9 +103,34 @@ You can even select arrays of UUIDs as `joinKey`. Booster get each value on the
 
 #### ReadModel queries
 
-You can use a read model query as a join key to get all the ReadModels that matches the query. Example:
+You can use a read model query as a join key to get all the read models that match the query. For example, consider the following read model for car purchases:
 
 ```typescript
+@ReadModel
+export class CarPurchasesReadModel {
+  public constructor(
+    readonly id: UUID,
+    readonly carModel?: string,
+    readonly carOwner?: string,
+    readonly offers?: Array<CarOffers>
+  ) {}
+
+  // rest of the code
+}
+```
+
+If a car model changed its name (or any other property of such an entity that's projected in `CarPurchasesReadModel` changed its value) and there are many purchases associated to that model, then it would be necessary to update all read model instances associated to that specific model so that name change is reflected. The better alternative is to instead project a `CarModel` entity:
+
+```typescript
+@ReadModel
+export class CarPurchasesReadModel {
+  public constructor(
+    readonly id: UUID,
+    readonly carModel?: CarModel,
+    readonly carOwner?: CarOwner,
+    readonly offers?: Array<CarOffers>
+  ) {}
+
   @Projects(CarModel, (carModel: CarModel): FilterFor<CarPurchasesReadModel> => {
     return {
       carModel: {
@@ -130,12 +155,22 @@ You can use a read model query as a join key to get all the ReadModels that matc
       oldCarPurchaseReadModel?.offers
     )
   }
+}
 ```
 
-This projection uses a ReadModel query JoinKey to get all the CarOwnerModelReadModel instances for a given CarModel. In this case, the `projectWithModel` function
-will be called for each CarOwnerModelReadModel instance that matches the query. The `readModelId` argument will be the id of the CarOwnerModelReadModel instance.
+Since the `CarModel` entity doesn't have a field that matches the `id` field of `CarPurchasesReadModel`, this projection can use a read model query join key to get all the `CarPurchasesReadModel` instances for a given `CarModel`.
+
+In this case, the `projectWithModel` function will be called for each `CarPurchasesReadModel` instance that matches the query. The `readModelId` argument will be the `id` of the `CarPurchasesReadModel` instance.
 
-> [!NOTE] If no read model matches the query, the `projectWithModel` function will be called with `readModelId` set to `undefined`.
+With this approach, every time there's a change in the `CarModel` entity it will be reflected in the read model without the need to manually update all read model instances.
+
+:::note
+If no read model matches the query, the `projectWithModel` function will be called with `readModelId` set to `undefined`.
+:::
+
+:::note
+Take a look at the [Getting, filtering and projecting read models data at code level](/graphql#getting-filtering-and-projecting-read-models-data-at-code-level) section for more information on how to filter read models.
+:::
 
 ### Returning special values
 

website/docs/03_architecture/08_queries.mdx

@@ -122,4 +122,6 @@ You will get the following GraphQL query and subscriptions:
 query CartTotalQuantityQuery($cartId: ID!): Float!
 ```
 
-> [!NOTE] Query subscriptions are not supported yet
+:::note
+Query subscriptions are not supported yet
+:::

website/docs/06_graphql.md

@@ -882,13 +882,21 @@ export class GetCartItems {
 
 The above search will return an array of carts with their `id` property, as well as an array of the `cartItems` of each cart with only the `productId` for each item.
 
-> **Warning**: Only available for Azure and Local Providers. `select` will be ignored for AWS Provider.
+:::warning
+Only available for Azure and Local Providers. `select` will be ignored for AWS Provider.
+:::
 
-> **Warning**: Using `select` will skip any Read Models migrations that need to be applied to the result. If you need to apply migrations to the result, don't use `select`.
+:::warning
+Using `select` will skip any Read Models migrations that need to be applied to the result. If you need to apply migrations to the result, don't use `select`.
+:::
 
-> **Warning**: Support for selecting fields from objects inside arrays is limited to arrays that are at most nested inside another property, e.g., `['category.relatedCategories[].name']`. Selecting fields from arrays that are nested deeper than that (e.g., `['foo.bar.items[].id']`) is not expected to yield the expected results.
+:::warning
+Support for selecting fields from objects inside arrays is limited to arrays that are at most nested inside another property, e.g., `['category.relatedCategories[].name']`. Selecting fields from arrays that are nested deeper than that (e.g., `['foo.bar.items[].id']`) is not expected to yield the expected results.
+:::
 
-> **Warning**: Notice that `ReadModel`s are eventually consistent objects that are calculated as all events in all entities that affect the read model are settled. You should not assume that a read model is a proper source of truth, so you shouldn't use this feature for data validations. If you need to query the most up-to-date current state, consider fetching your Entities, instead of ReadModels, with `Booster.entity`
+:::warning
+Notice that `ReadModel`s are eventually consistent objects that are calculated as all events in all entities that affect the read model are settled. You should not assume that a read model is a proper source of truth, so you shouldn't use this feature for data validations. If you need to query the most up-to-date current state, consider fetching your Entities, instead of ReadModels, with `Booster.entity`
+:::
 
 ### Using sorting
 
@@ -931,7 +939,9 @@ This is a preview feature available only for some Providers and with some limita
   - Nested fields supported.
   - Sort by more than one file: **unsupported**.
 
-> **Warning**: It is not possible to sort by fields defined as Interface, only classes or primitives types.
+:::warning
+It is not possible to sort by fields defined as Interface, only classes or primitives types.
+:::
 
 ### Using pagination
 

website/docs/10_going-deeper/azure-scale.mdx

@@ -10,7 +10,9 @@ With Booster EventStream functionality, we could define the number of physical p
 
 To enable EventStream, set the `EventStreamConfiguration` in the configuration object:
 
-> **Warning**: Currently, only available for Azure provider.
+:::warning
+Currently, only available for Azure provider.
+:::
 
 ```typescript
   config.eventStreamConfiguration = {

website/docs/10_going-deeper/health/sensor-health.md

@@ -316,13 +316,17 @@ export class ApplicationHealthIndicator {
     * file: Read Models database file
     * count: number of total rows
 
-> **Note**: details will be included only if `details` is enabled
+:::note
+Details will be included only if `details` is enabled
+:::
 
 #### rockets
 
 * status: UP if and only if all rockets are UP, PARTIALLY_UP if not all rockets are UP
 
-> **Note**: sensors for rockets is only available for the Azure provider
+:::note
+Sensors for rockets is only available for the Azure provider
+:::
 
 ### Health status
 

website/docs/10_going-deeper/remove-events.mdx

@@ -1,6 +1,8 @@
 # Remove events
 
-> **Warning**: This is an experimental functionality. Please note that this functionality is only supported by Azure and Local providers.
+:::warning
+This is an experimental functionality. Please note that this functionality is only supported by Azure and Local providers.
+:::
 
 Booster allows to delete past events and their related entities as to update the affected ReadModels.
 
@@ -88,4 +90,6 @@ Example:
 
 ([See more details about how to delete a ReadModel in the docs](https://docs.boosterframework.com/architecture/read-model/#deleting-read-models))
 
-> **Warning**: Please note that these changes are final and it is not possible to retrieve the information once they have been made.
+:::warning
+Please note that these changes are final and it is not possible to retrieve the information once they have been made.
+:::

website/docs/12_contributing.md

@@ -55,7 +55,9 @@ Contributing to an open source project is never just a matter of code, you can h
 
 Before creating a bug report, please search for similar issues to make sure that they're not already reported. If you don't find any, go ahead and create an issue including as many details as possible. Fill out the required template, the information requested helps us to resolve issues faster.
 
-> **Note**: If you find a Closed issue that seems related to the issues that you're experiencing, make sure to reference it in the body of your new one by writing its number like this => #42 (Github will autolink it for you).
+:::note
+If you find a Closed issue that seems related to the issues that you're experiencing, make sure to reference it in the body of your new one by writing its number like this => #42 (Github will autolink it for you).
+:::
 
 Bugs are tracked as GitHub issues. Explain the problem and include additional details to help maintainers reproduce the problem: