Working on an overhaul for the teams documentation.

app/controllers/api/teams.php

@@ -32,7 +32,7 @@ App::post('/v1/teams')
     ->label('sdk.response.code', Response::STATUS_CODE_CREATED)
     ->label('sdk.response.type', Response::CONTENT_TYPE_JSON)
     ->label('sdk.response.model', Response::MODEL_TEAM)
-    ->param('name', null, new Text(128), 'Team name. Max length: 128 chars.')
+    ->param('name', null, new Text(128), 'The name of the team. Max length: 128 chars.')
     ->param('roles', ['owner'], new ArrayList(new Key()), 'Array of strings. Use this param to set the roles in the team for the user who created it. The default role is **owner**. A role can be any string. Learn more about [roles and permissions](/docs/permissions). Max length for each role is 32 chars.', true)
     ->inject('response')
     ->inject('user')
@@ -113,10 +113,10 @@ App::get('/v1/teams')
     ->label('sdk.response.code', Response::STATUS_CODE_OK)
     ->label('sdk.response.type', Response::CONTENT_TYPE_JSON)
     ->label('sdk.response.model', Response::MODEL_TEAM_LIST)
-    ->param('search', '', new Text(256), 'Search term to filter your list results. Max length: 256 chars.', true)
-    ->param('limit', 25, new Range(0, 100), 'Results limit value. By default will return maximum 25 results. Maximum of 100 results allowed per request.', true)
-    ->param('offset', 0, new Range(0, 2000), 'Results offset. The default value is 0. Use this param to manage pagination.', true)
-    ->param('orderType', 'ASC', new WhiteList(['ASC', 'DESC'], true), 'Order result by ASC or DESC order.', true)
+    ->param('search', '', new Text(256), 'Enter any text to search. Max length: 256 chars.', true)
+    ->param('limit', 25, new Range(0, 100), 'Limit how many results will be returned. Returns 25 results by default. Maximum of 100 results allowed per request.', true)
+    ->param('offset', 0, new Range(0, 2000), 'Use this value to manage pagination. The default value is 0.', true)
+    ->param('orderType', 'ASC', new WhiteList(['ASC', 'DESC'], true), 'Use ASC to order results in ascending and DESC to order results in descending order.', true)
     ->inject('response')
     ->inject('projectDB')
     ->action(function ($search, $limit, $offset, $orderType, $response, $projectDB) {
@@ -178,8 +178,8 @@ App::put('/v1/teams/:teamId')
     ->label('sdk.response.code', Response::STATUS_CODE_OK)
     ->label('sdk.response.type', Response::CONTENT_TYPE_JSON)
     ->label('sdk.response.model', Response::MODEL_TEAM)
-    ->param('teamId', '', new UID(), 'Team unique ID.')
-    ->param('name', null, new Text(128), 'Team name. Max length: 128 chars.')
+    ->param('teamId', '', new UID(), 'The unique team ID.')
+    ->param('name', null, new Text(128), 'The new team name. Max length: 128 chars.')
     ->inject('response')
     ->inject('projectDB')
     ->action(function ($teamId, $name, $response, $projectDB) {
@@ -214,7 +214,7 @@ App::delete('/v1/teams/:teamId')
     ->label('sdk.description', '/docs/references/teams/delete-team.md')
     ->label('sdk.response.code', Response::STATUS_CODE_NOCONTENT)
     ->label('sdk.response.model', Response::MODEL_NONE)
-    ->param('teamId', '', new UID(), 'Team unique ID.')
+    ->param('teamId', '', new UID(), 'The unique team ID.')
     ->inject('response')
     ->inject('projectDB')
     ->inject('events')

docs/references/teams/create-team.md

@@ -1 +1 @@
-Create a new team. The user who creates the team will automatically be assigned as the owner of the team. The team owner can invite new members, who will be able add new owners and update or delete the team from your project.
+Use this endpoint to create a new team. The user who creates the team will automatically be assigned as the owner of the team. Only the users with the owner role can invite new members or add new owners. However, every member can delete or update the team.

docs/references/teams/delete-team.md

@@ -1 +1 @@
-Delete a team by its unique ID. Only team owners have write access for this resource.
+Delete a team using its unique ID. Every member of the team has access to this endpoint.

docs/references/teams/list-teams.md

@@ -1 +1,3 @@
-Get a list of all the current user teams. You can use the query params to filter your results. On admin mode, this endpoint will return a list of all of the project's teams. [Learn more about different API modes](/docs/admin).
+Get a list of all the teams in which the current user is a member. You can use the parameters to filter your results.
+
+On admin mode, this endpoint returns a list of all the teams in the current project. [Learn more about different API modes](/docs/admin).

docs/references/teams/update-team.md

@@ -1 +1 @@
-Update a team by its unique ID. Only team owners have write access for this resource.
+Update a team using its unique ID. Every team member has access to this endpoint.