improvement: small improvements to the writing structure

content/cookbooks/testing-adonisjs-apps.md

@@ -233,8 +233,10 @@ Now, re-run the tests by executing `node -r @adonisjs/assembler/build/register j
 
 The next step is to write a test that interacts the database. But first, let's update the `japaFile.ts` file to run and rollback migrations everytime we run the tests. This way, we will ensure that we are always starting from a clean database.
 
-:::note
-If you do not want to overwrite your current database, remember to create a `.env.testing` that overwrite your database environement variables.
+:::tip
+
+You can also configure a separate database for testing by creating `.env.testing` file in the project root and [overwriting the neccessary](../guides/fundamentals/environment-variables.md#defining-variables-while-testing) environment variables.
+
 :::
 
 ```ts

content/guides/fundamentals/environment-variables.md

@@ -26,12 +26,6 @@ Env.get('HOST', '0.0.0.0')
 Env.get('PORT', 3333)
 ```
 
-## Environment variables while testing
-
-When running tests, you may want to overwrite some of your environment variables. For example, you need to access another database to avoid crushing your data. You can achieve that by creating an `.env.testing` file.
-
-All variables contained inside this file will be merged automatically with your `.env` file.
-
 ## Why validate environment variables?
 
 Environment variables are injected from outside-in to your application, and you have little or no control over them within your codebase.
@@ -206,7 +200,7 @@ For every other validation use case, you can define your own custom functions.
 - The return value can be different from the initial input value.
 - We infer the static type from the return value. In this case, `Env.get('PORT')` is a number.
 
-## Defining variables in the development
+## Defining variables in development
 
 During development, you can define environment variables inside the `.env` file stored in your project's root and AdonisJS will automatically process it.
 
@@ -261,6 +255,12 @@ The `.env` file can be at any location on your server. For example, You can stor
 ENV_PATH=/etc/myapp/.env node server.js
 ```
 
+## Defining variables while testing
+
+AdonisJS will look for `.env.testing` file when the application is started with the `NODE_ENV=testing` environment variable.
+
+The variables defined inside the `.env.testing` file are automatically merged with the `.env` file. This allows you to use a different database, or a different session driver when writing tests.
+
 ## Defining variables in production
 
 Most modern-day hosting providers have first-class support for defining environment variables within their web console. Make sure you read the documentation for your hosting provider and define the environment variables before deploying your AdonisJS app.

content/guides/models/crud.md

@@ -7,7 +7,9 @@ Lucid models make it very easy to perform CRUD operations and also define lifecy
 This guide covers 80% of the use cases. However, do make sure to check the [Model API docs](../../reference/orm/base-model.md) docs for all the available methods.
 
 ## Create
-You can create and persist new records to the database by assigning values to the model instance properties and calling the `model.save` method.
+You can create and persist new records to the database by first assigning values to the model instance and then calling the `save` method.
+
+The `save` method performs the **INSERT** query when persisting the model instance for the first time and performs the **UPDATE** query when model has already been persisted.
 
 ```ts
 import User from 'App/Models/User'
@@ -23,13 +25,20 @@ await user.save()
 console.log(user.$isPersisted) // true
 ```
 
-- The `user.save` method will perform the insert query. 
-- The `user.$isPersisted` flag returns `true` when the values are persisted to the database.
+Also, you can make use of the `fill` method to define all the attributes as once and then call the `save` method.
+
+```ts
+await user
+ .fill({ username: 'virk', email: '[email protected]' })
+ .save()
+
+console.log(user.$isPersisted) // true
+```
 
 ---
 
 ### create
-Another option is to make use of the `static create` method on the Model class itself.
+The `static create` method creates the model instance and persists it to database in one go.
 
 ```ts
 import User from 'App/Models/User'
@@ -156,9 +165,14 @@ const user = await User.findOrFail(1)
 user.last_login_at = DateTime.local() // Luxon dateTime is used
 
 await user.save()
+```
 
-// OR
-// await user.merge({ last_login_at: DateTime.local() }).save()
+Also, you can make use of the `merge` method to define all the attributes as once and then call the `save` method.
+
+```ts
+await user
+ .merge({ last_login_at: DateTime.local() })
+ .save()
 ```
 
 #### Why not use the update query directly?