[Docs] Update teams-permissions.md for readability

docs/basic-usage/teams-permissions.md

@@ -3,9 +3,14 @@ title: Teams permissions
 weight: 3
 ---
 
-NOTE: Those changes must be made before performing the migration. If you have already run the migration and want to upgrade your solution, you can run the artisan console command `php artisan permission:setup-teams`, to create a new migration file named [xxxx_xx_xx_xx_add_teams_fields.php](https://github.com/spatie/laravel-permission/blob/main/database/migrations/add_teams_fields.php.stub) and then run `php artisan migrate` to upgrade your database tables.
+When enabled, teams permissions offers you flexible control for a variety of scenarios. The idea behind teams permissions is inspired by the default permission implementation of [Laratrust](https://laratrust.santigarcor.me/).
 
-When enabled, teams permissions offers you a flexible control for a variety of scenarios. The idea behind teams permissions is inspired by the default permission implementation of [Laratrust](https://laratrust.santigarcor.me/).
+
+## Enabling Teams Permissions Feature
+
+NOTE: These configuration changes must be made **before** performing the migration when first installing the package.
+
+If you have already run the migration and want to upgrade your implementation, you can run the artisan console command `php artisan spatie-permission:setup-teams`, to create a new migration file named [xxxx_xx_xx_xx_add_teams_fields.php](https://github.com/spatie/laravel-permission/blob/main/database/migrations/add_teams_fields.php.stub) and then run `php artisan migrate` to upgrade your database tables.
 
 
 Teams permissions can be enabled in the permission config file:
@@ -15,7 +20,7 @@ Teams permissions can be enabled in the permission config file:
 'teams' => true,
 ```
 
-Also, if you want to use a custom foreign key for teams you must change in the permission config file:
+Also, if you want to use a custom foreign key for teams you set it in the permission config file:
 ```php
 // config/permission.php
 'team_foreign_key' => 'custom_team_id',
@@ -24,7 +29,9 @@ Also, if you want to use a custom foreign key for teams you must change in the p
 ## Working with Teams Permissions
 
 After implementing a solution for selecting a team on the authentication process (for example, setting the `team_id` of the currently selected team on the **session**: `session(['team_id' => $team->team_id]);` ), 
-we can set global `team_id` from anywhere, but works better if you create a `Middleware`. Example:
+we can set global `team_id` from anywhere, but works better if you create a `Middleware`. 
+
+Example Team Middleware:
 
 ```php
 namespace App\Http\Middleware;
@@ -46,17 +53,17 @@ class TeamsPermission{
     }
 }
 ```
-NOTE: You must add your custom `Middleware` to `$middlewarePriority` on `app/Http/Kernel.php`.
+NOTE: You must add your custom `Middleware` to `$middlewarePriority` in `app/Http/Kernel.php`.
 
 ## Roles Creating
 
 When creating a role you can pass the `team_id` as an optional parameter
 
 ```php
-// with null team_id it creates a global role, global roles can be assigned to any team and they are unique
+// with null team_id it creates a global role; global roles can be assigned to any team and they are unique
 Role::create(['name' => 'writer', 'team_id' => null]);
 
-// creates a role with team_id = 1, team roles can have the same name on different teams
+// creates a role with team_id = 1; team roles can have the same name on different teams
 Role::create(['name' => 'reader', 'team_id' => 1]);
 
 // creating a role without team_id makes the role take the default global team_id
@@ -65,11 +72,13 @@ Role::create(['name' => 'reviewer']);
 
 ## Roles/Permissions Assignment & Removal
 
-The role/permission assignment and removal are the same, but they take the global `team_id` set on login for sync.
+The role/permission assignment and removal for teams are the same as without teams, but they take the global `team_id` set on login for sync.
 
 ## Defining a Super-Admin on Teams
 
-Global roles can be assigned to different teams, `team_id` as the primary key of the relationships is always required. If you want a "Super Admin" global role for a user, when you creates a new team you must assign it to your user. Example:
+Global roles can be assigned to different teams, and `team_id` as the primary key of the relationships is always required. 
+
+If you want a "Super Admin" global role for a user, when you create a new team you must assign it to your user. Example:
 
 ```php
 namespace App\Models;
@@ -83,13 +92,13 @@ class YourTeamModel extends \Illuminate\Database\Eloquent\Model
 
         // here assign this team to a global user with global default role
         self::created(function ($model) {
-           // get session team_id for restore it later
+           // temporary: get session team_id for restore at end
            $session_team_id = getPermissionsTeamId();
            // set actual new team_id to package instance
            setPermissionsTeamId($model);
            // get the admin user and assign roles/permissions on new team model
            User::find('your_user_id')->assignRole('Super Admin');
-           // restore session team_id to package instance
+           // restore session team_id to package instance using temporary value stored above
            setPermissionsTeamId($session_team_id);
         });
     }