added reusables, feature flag and other updates

Author: saritai

content/code-security/getting-started/securing-your-organization.md

@@ -22,11 +22,7 @@ Some security features are only available {% ifversion fpt %}for public reposito
 
 ## Managing access to your organization
 
-You can use roles to control what actions people can take in your organization. For more information, see "[Roles in an organization](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization)."
-
-{% ifversion fpt or ghes > 3.2 or ghae-issue-4999 %}
-You can assign the security manager role to security teams in your organization to give them security management permissions exclusively, without extra permissions that they do not require. For more information, see "[Managing the security manager role in your organization](/organizations/managing-peoples-access-to-your-organization-with-roles/managing-the-security-manager-role-in-your-organization)."
-{% endif %}
+You can use roles to control what actions people can take in your organization. {% if security-managers %}For example, you can assign the security manager role to a team to give them the ability to manage security settings across your organization, as well as read access to all repositories.{% endif %} For more information, see "[Roles in an organization](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization)."
 
 {% ifversion fpt or ghes > 3.0 or ghae-next %}
 

content/organizations/managing-peoples-access-to-your-organization-with-roles/index.md

@@ -18,7 +18,7 @@ children:
   - /giving-team-maintainer-permissions-to-an-organization-member
   - /adding-a-billing-manager-to-your-organization
   - /removing-a-billing-manager-from-your-organization
-  - /managing-the-security-manager-role-in-your-organization
+  - /managing-security-managers-in-your-organization
 shortTitle: Manage access with roles
 ---
 

…ity-manager-role-in-your-organization.md …ecurity-managers-in-your-organization.mdcontent/organizations/managing-peoples-access-to-your-organization-with-roles/managing-the-security-manager-role-in-your-organization.md renamed to content/organizations/managing-peoples-access-to-your-organization-with-roles/managing-security-managers-in-your-organization.md content/organizations/managing-peoples-access-to-your-organization-with-roles/managing-the-security-manager-role-in-your-organization.md renamed to content/organizations/managing-peoples-access-to-your-organization-with-roles/managing-security-managers-in-your-organization.md

@@ -1,40 +1,33 @@
 ---
-title: Managing the security manager role in your organization
+title: Managing security managers in your organization
 intro: 'You can give your security team the least access they need to your organization by assigning a team to the security manager role.'
 versions:
-  fpt: '*'
-  ghes: '>=3.3'
-  ghae: 'issue-4999'
+  feature: 'security-managers'
 topics:
   - Organizations
   - Teams
 shortTitle: Security manager role
 permissions: Organization owners can assign the security manager role.
 ---
 
-{% note %}
+{% data reusables.organizations.security-manager-beta-note %}
 
-**Note:** The security manager role is in public beta and subject to change.
-
-{% endnote %}
-
-Organization owners can grant a team the permissions they need to manage security alerts and settings across your organization, as well as read access on all organization repositories, by assigning the security manager role.
+{% data reusables.organizations.about-security-managers %}
 
 ## Permissions for the security manager role
 
 Members of a team with the security manager role have only the permissions required to effectively manage security for the organization.
 
-- Read access on all repositories in the organization, in addition to any existing repository access 
+- Read access on all repositories in the organization, in addition to any existing repository access
 - Write access on all security alerts in the organization
 - Access to the organization's security overview
 - The ability to configure security settings at the organization level, including the ability to enable or disable {% data variables.product.prodname_GH_advanced_security %}
 - The ability to configure security settings at the repository level, including the ability to enable or disable {% data variables.product.prodname_GH_advanced_security %}
 
-While a team will be granted read permission on all organization repositories upon being added as security managers, any existing repository permissions that the team had will stay the same. If a team has the security manager role, only organization owners will be able to change team access to repositories in the **Repositories** tab. 
+If a team has the security manager role, only organization owners can change the team's access to individual repositories. People with admin access to a repository can see the team's access in the repository's settings but cannot remove or change the access. For more information, see "[Managing team access to an organization repository](/organizations/managing-access-to-your-organizations-repositories/managing-team-access-to-an-organization-repository)" and "[Managing teams and people with access to your repository](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-teams-and-people-with-access-to-your-repository)."
 
-Repository owners will be able to see if a security manager team has access to their repository in the **Manage access** tab in their repository settings. Under **Manage direct access**, any security manager teams will appear as **Managed by organization owners**  and their permissions cannot be removed or edited by the repository owner.
+  ![Manage repository access disabled with security managers](/assets/images/help/organizations/repo-access-security-managers.png)
 
-  ![Manage repository access with security managers](/assets/images/help/organizations/repo-access-security-managers.png)
 ## Assigning the security manager role to a team in your organization
 
 {% data reusables.profile.access_org %}
@@ -44,12 +37,11 @@ Repository owners will be able to see if a security manager team has access to t
   ![Add security manager](/assets/images/help/organizations/add-security-managers.png)
 ## Removing the security manager role from a team in your organization
 
-
 {% warning %}
 
 **Warning:** Removing the security manager role from a team will remove the team's ability to manage security alerts and settings across the organization, but the team will retain read access to repositories that was granted when the role was assigned. You must remove any unwanted read access manually. For more information, see "[Managing team access to an organization repository](/organizations/managing-access-to-your-organizations-repositories/managing-team-access-to-an-organization-repository#removing-a-teams-access-to-a-repository)."
 
-{% end warning %}
+{% endwarning %}
 
 {% data reusables.profile.access_org %}
 {% data reusables.profile.org_settings %}

content/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization.md

@@ -18,36 +18,35 @@ shortTitle: Roles in an organization
 ## About roles
 {% data reusables.organizations.about-roles %}
 
-You can give organization members, outside collaborators and teams of people varying levels of access to repositories by assigning repository roles. For more information, see "[Repository roles for an organization](/organizations/managing-access-to-your-organizations-repositories/repository-roles-for-an-organization)."
+Repository-level roles give organization members, outside collaborators and teams of people varying levels of access to repositories. For more information, see "[Repository roles for an organization](/organizations/managing-access-to-your-organizations-repositories/repository-roles-for-an-organization)."
 
 Team-level roles are roles that give permissions to manage a team. You can give any individual member of a team the team maintainer role, which gives the member a number of administrative permissions over a team. For more information, see "[Giving "team maintainer" permissions to an organization member](/organizations/managing-peoples-access-to-your-organization-with-roles/giving-team-maintainer-permissions-to-an-organization-member)."
 
-Organization-level roles are different sets of permissions that can be assigned to individuals or teams to manage an organization and the repositories, teams and settings within it. For more information on each organization-level role, see [Roles for an organization](#roles-for-an-organization).
+Organization-level roles are sets of permissions that can be assigned to individuals or teams to manage an organization and the organization's repositories, teams, and settings. For more information about all the roles available at the organization level, see "[About organization roles](#about-organization-roles)."
+
+## About organization roles
+
+You can assign individuals or teams to a variety of organization-level roles to control your members' access to your organization and its resources. For more details about the individual permissions included in each role, see "[Permissions for organization roles](#permissions-for-organization-roles)."
 
-## Roles for an organization
 ### Organization owners
 Organization owners have complete administrative access to your organization. This role should be limited, but to no less than two people, in your organization. For more information, see "[Maintaining ownership continuity for your organization](/organizations/managing-peoples-access-to-your-organization-with-roles/maintaining-ownership-continuity-for-your-organization)."
 
 ### Organization members
-The default, non-administrative role for people in an organization is the organization member. Organization members have a number of permissions, including being able to create repositories and project boards. 
+The default, non-administrative role for people in an organization is the organization member. By default, organization members have a number of permissions, including the ability to create repositories and project boards.
 
 {% ifversion fpt %}
 ### Billing managers
 Billing managers are users who can manage the billing settings for your organization, such as payment information. This is a useful option if members of your organization don't usually have access to billing resources. For more information, see "[Adding a billing manager to your organization](/organizations/managing-peoples-access-to-your-organization-with-roles/adding-a-billing-manager-to-your-organization)."
 {% endif %}
 
-{% ifversion fpt or ghes > 3.2 or ghae-issue-4999 %}
+{% if security-managers %}
 ### Security managers
 
-{% note %}
-
-**Note:** The security manager role is in public beta and subject to change.
-
-{% endnote %}
+{% data reusables.organizations.security-manager-beta-note %}
 
-Security manager is an organization-level role that can be assigned to any team in an organization. When applied, it gives every member of the team permissions to manage security alerts and settings across your organization, as well as read permissions for all repositories in the organization.
+{% data reusables.organizations.about-security-managers %}
 
-If your organization has a security team, you can use the security manager role to give members of that team the permissions they need to do their job without any extra permissions they do not require. For more information, see "[Managing the security manager role in your organization](/organizations/managing-peoples-access-to-your-organization-with-roles/managing-the-security-manager-role-in-your-organization)."
+If your organization has a security team, you can use the security manager role to give members of the team the least access they need to the organization. For more information, see "[Managing security managers in your organization](/organizations/managing-peoples-access-to-your-organization-with-roles/managing-security-managers-in-your-organization)."
 {% endif %}
 ### {% data variables.product.prodname_github_app %} managers
 By default, only organization owners can manage the settings of {% data variables.product.prodname_github_apps %} owned by an organization. To allow additional users to manage {% data variables.product.prodname_github_apps %} owned by an organization, an owner can grant them {% data variables.product.prodname_github_app %} manager permissions.
@@ -128,8 +127,9 @@ Some of the features listed below are limited to organizations using {% data var
 | Enable team synchronization (see "[Managing team synchronization for your organization](/organizations/managing-saml-single-sign-on-for-your-organization/managing-team-synchronization-for-your-organization)" for details) | **X** |  | |  |
 
 {% elsif ghes > 3.2 or ghae-issue-4999 %}
+<!--GHES 3.3+ and eventual GHAE release don't have the extra column for Billing managers, but have security managers-->
 
-| Organization action test | Owners | Members | Security managers |
+| Organization action | Owners | Members | Security managers |
 |:--------------------|:------:|:-------:|:-------:|
 | Invite people to join the organization | **X** |  |  |
 | Edit and cancel invitations to join the organization | **X** |  |  |
@@ -172,7 +172,7 @@ Some of the features listed below are limited to organizations using {% data var
 
 
 {% else %}
-<!--GHE version doesn't have the extra column for Billing managers-->
+<!--GHES and GHAE older versions don't have the extra column for Billing managers or Security managers-->
 
 | Organization action | Owners | Members |
 |:--------------------|:------:|:-------:|

data/features/security-managers.yml

@@ -0,0 +1,6 @@
+# Reference: #4999.
+# Documentation for the security manager org-level role
+versions:
+  fpt: '*'
+  ghes: '>=3.3'
+  ghae: 'issue-4999'

data/reusables/organizations/about-security-managers.md

@@ -0,0 +1 @@
+Security manager is an organization-level role that organization owners can assign to any team in an organization. When applied, it gives every member of the team permissions to manage security alerts and settings across your organization, as well as read permissions for all repositories in the organization.

data/reusables/organizations/security-manager-beta-note.md

@@ -0,0 +1,5 @@
+{% note %}
+
+**Note:** The security manager role is in public beta and subject to change.
+
+{% endnote %}