(docs): After the call, I have a much better understanding of this. Implementing Paz's feedback, making these pages much easier to read, and flow better.

Author: dericksozo

docs/getting-started/add-custom-code.md

@@ -1,13 +1,14 @@
 ---
 id: add-custom-code
 title: Adding Custom Code to Your Amplication Service
-sidebar_label: Adding Custom Code
+sidebar_label: Add Custom Code To Your Service
 slug: /add-custom-code-to-your-service
 ---
 
-# Adding Custom Code to Your Amplication Service
+# Add Custom Code To Your Service
 
-While Amplication generates a robust, production-ready backend for your application, you'll often need to add custom business logic or additional functionality. This guide explains how Amplication manages custom code alongside generated code, and provides best practices for adding your own code to an Amplication-generated service.
+Amplication generates a robust, production-ready backend for your app, but you'll often need to add your own custom business logic with custom code.
+In this guide you'll learn how to add custom code to your Amplication service with a simple example.
 
 ## Prerequisites
 
@@ -20,12 +21,13 @@ Before you begin, make sure you know to:
 5. [Commit changes and build a new version](/commit-and-build-new-versions/)
 
 :::note
-For more a more in-depth explanation, read [Understanding Custom Code in Amplication](/custom-code-overview/)
+For more a more in-depth explanation of how custom code works, read [Understanding Custom Code in Amplication](/custom-code-overview/).
 :::
 
-## Adding Custom Code: A Simple Example
+## Adding Custom Code: Retrieve The User's Full Name
 
 Let's walk through a simple example of adding custom code to your service.
+In this example, we'll add a method with custom code to get the user's full name.
 
 ### Step 1: Create A New Feature Branch
 
@@ -41,9 +43,9 @@ Next, create a new branch from the main branch to make your custom code changes:
 git checkout -b feature/user-full-name
 ```
 
-### Step 2: Locate the Correct Files
+### Step 2: Locate the Correct File
 
-Navigate to your service's `src` folder and find the `user` folder:
+Navigate to the code of your generated service's `src` folder and find the `user` folder:
 
 ```
 src
@@ -58,11 +60,16 @@ src
     └── user.service.ts
 ```
 
-We'll be modifying `user.service.ts` to add our custom functionality.
+We'll modify the `user.service.ts` to add our custom functionality.
+
+:::tip
+Notice that we're adding our changes to `user.service.ts` instead of `base/user.service.base.ts` file.
+To learn more why we recommend doing this, read [Understanding Custom Code in Amplication](/custom-code-overview/).
+:::
 
 ### Step 3: Add Custom Logic to the Service
 
-Open `src/user/user.service.ts`. This file extends the base service and is where we'll add our custom method.
+Open `src/user/user.service.ts`. This file extends the base service and is where we'll add our custom method that retrieves the user's full name.
 
 ```typescript
 import { Injectable } from "@nestjs/common";
@@ -77,11 +84,11 @@ export class UserService extends UserServiceBase {
 }
 ```
 
-This example adds a simple method to get a user's full name. Note how it uses the `findOne` method from the base service.
+Note how it uses the `findOne` method from the base service.
 
 ### Step 4: Push Your Changes
 
-After adding your custom code, commit the changes to your git repository:
+After adding your custom code, commit the changes to the git feature branch you created in Step 1:
 
 ```bash
 git add .

docs/how-to/add-custom-code.md

@@ -9,18 +9,20 @@ pagination_next: getting-started/add-custom-code
 # Understanding Custom Code in Amplication
 
 Amplication allows seamless integration of your custom code with generated code through our [Smart Git Sync](/smart-git-sync) feature.
-
 This lets you add custom business logic while continuing to use Amplication to update your data models, permissions, roles, plugins, and more.
 
+This guide is an in-depth explanation on how custom code works in your Amplication project.
+
 ## How Custom Code Integration Works
 
-1. Custom code can be added to _all files_ in your Amplication project.
-2. Amplication uses a specific folder structure to manage base and non-base files.
-3. The `base` folder contains generated files that will get updates only if there are relevant changes.
-4. Non-base files are intended for custom code.
-5. If necessary changes to non-base files are required (e.g., removing references to a deleted plugin), Amplication will make these changes automatically.
+1. Amplication uses a specific folder structure to manage base and non-base files.
+2. The `base` folder contains generated files that will get updates only if there are relevant changes (e.g., you add a new plugin).
+3. Non-base files are intended for custom code.
+4. Amplication will make necessary changes to both base and non-base files (e.g., updating interfaces, removing references to deleted plugins) while always preserving and respecting your custom code.
 
-Amplication always respects your custom code and syncs it with the generated code in both base and non-base files.
+:::tip
+While you can add custom code to _all files_, we recommend primarily adding custom code to non-base files (e.g., `user.service.ts` instead of `user.service.base.ts`) for easier maintenance.
+:::
 
 ## Folder Structure
 
@@ -36,9 +38,13 @@ Each entity has a dedicated folder under the `src` folder:
 
 Within each entity folder, files are split into two groups:
 
-1. **Base files**: Located in the `base` folder, these are automatically generated by Amplication.
+### Base files
+
+**Base files**: Located in the `base` folder, these are automatically generated by Amplication.
+
+### Non-base Files
 
-2. **Non-base files**: These inherit from the base files and are intended for your custom code. They reside directly in the entity folder. Your custom code is always preserved and respected across builds.
+**Non-base files**: These inherit from the base files and are intended for your custom code. They reside directly in the entity folder.
 
 ```
 src
@@ -52,43 +58,38 @@ src
     └── ...
 ```
 
+Your custom code, whether it's in base or non-file files, is always preserved and respected across builds.
+
 ## Smart Git Sync
 
 Amplication uses [Smart Git Sync](/smart-git-sync/) to seamlessly integrate changes, preserving your custom code while updating the generated parts. This feature:
 
-1. Preserves and always respects custom code in base and non-base files.
-2. Makes necessary updates to non-base ,files (e.g., removing references to deleted plugins) while maintaining your custom code.
+Makes necessary updates to both base and non-base files (e.g., updating interfaces, removing references to deleted plugins) while respecting your custom code.
 
 :::note
-For a more in-depth explanation, please see the [Smart Git Sync](/smart-git-sync) page.
+For a more in-depth explanation, please read the [Smart Git Sync](/smart-git-sync) page.
 :::
 
 ## Best Practices for Custom Code
 
 When adding custom code to your Amplication service, keep these best practices in mind:
 
-1. Add custom code to non-base files (e.g., `user.service.ts` instead of `user.service.base.ts`).
-2. Use types and interfaces generated by Amplication to ensure type safety.
-3. Leverage existing services and utilities provided by Amplication.
-4. Document your custom code thoroughly.
-5. Create a new branch for significant custom code changes.
-6. Regularly pull and merge the latest Amplication-generated code from the `amplication` branch into your working branch.
-
-## Handling Conflicts
+1. Use types and interfaces generated by Amplication to ensure type safety.
+2. Leverage existing services and utilities provided by Amplication.
+3. Create a new feature branch for significant custom code changes.
+4. Regularly pull and merge the latest Amplication-generated code from the `amplication` branch into your working branch (e.g., `main`).
 
-While Amplication strives to preserve your custom code, conflicts may arise, especially with significant changes to your data model or entity structure. If conflicts occur:
+## How To Handle Conflicts
 
-1. Amplication will provide clear indications of the conflicting areas using git diffs in your chosen git provider.
-2. You may need to manually resolve these conflicts in the `amplication` branch.
-3. After resolving conflicts, merging the updated `amplication` branch into the main branch.
+While Amplication strives to preserve your custom code, conflicts may arise, especially with significant changes to your data model or entity structure. 
 
-## Considerations
+If conflicts arise during this process, you'll need to resolve them manually in the `amplication` branch before merging into your main branch.
 
-- While all code can be customized, we recommend adding custom code in the non-base files for easier maintenance.
-- Major changes to your data model or entity structure may require manual updates to your custom code.
+1. Amplication will provide clear indications of the conflicting areas using git diffs in your chosen git provider.
+2. You'll need to manually resolve these conflicts in the `amplication` branch.
+3. After resolving conflicts, merge the updated `amplication` branch into the main branch.
 
 ## Next Steps
 
-Now that you understand how custom code works in Amplication, you're ready to start adding your own business logic and customizations. For a step-by-step guide, check out our [How To Add Custom Code To Your Service](/add-custom-code-to-your-service) guide.
-
-Happy coding!
+Now that you understand how custom code works in Amplication, you're ready to start adding your own business logic.
+For a step-by-step guide, check out our [How To Add Custom Code To Your Service](/add-custom-code-to-your-service) guide.