Best practices for repositories, organizations, and enterprises (#32102)

Co-authored-by: Matt Pollard <mattpollard@users.noreply.github.com>

content/admin/identity-and-access-management/managing-iam-for-your-enterprise/about-authentication-for-your-enterprise.md

@@ -21,7 +21,7 @@ topics:
 
 Enterprise owners on {% data variables.product.product_name %} can control the requirements for authentication and access to the enterprise's resources. 
 
-You can choose to allow members to create and manage user accounts, or your enterprise can create and manage accounts for members with {% data variables.product.prodname_emus %}. If you allow members to manage their own accounts, you can also configure SAML authentication to both increase security and centralize identity and access for the web applications that your team uses.
+{% data reusables.enterprise.ghec-authentication-options %}
 
 After learning more about these options, to determine which method is best for your enterprise, see "[Identifying the best authentication method for your enterprise](#identifying-the-best-authentication-method-for-your-enterprise)."
 

content/admin/overview/best-practices-for-enterprises.md

@@ -0,0 +1,49 @@
+---
+title: Best practices for enterprises
+shortTitle: Best practices
+intro: Learn {% data variables.product.company_short %}-recommended practices for your enterprise.
+versions:
+  ghec: '*'
+  ghes: '*'
+  ghae: '*'
+type: overview
+topics:
+  - Accounts
+  - Enterprise
+  - Fundamentals
+---
+
+{% ifversion ghec %}
+## Identify the best authentication method for your enterprise
+
+{% data reusables.enterprise.ghec-authentication-options %}
+
+For help identifying the authentication method that will best meet your needs, see "[About authentication for your enterprise](/admin/identity-and-access-management/managing-iam-for-your-enterprise/about-authentication-for-your-enterprise)." 
+{% endif %}
+
+## Use policies
+
+We recommend using policies to enforce business rules and regulatory compliance. 
+
+{% data reusables.enterprise.about-policies %} For more information, see "[About enterprise policies](/admin/policies/enforcing-policies-for-your-enterprise/about-enterprise-policies)."
+
+## Minimize the number of organizations
+
+Large enterprises often need multiple organizations, but try to create as few as possible to reflect top-level corporate divisions. A smaller number of organizations encourages innersource practices and allows discussions to involve a wider audience.
+
+Instead, you can manage repository access and security requirements at a more granular level within each organization by using teams. For more information, see "[About teams](/organizations/organizing-members-into-teams/about-teams)."
+
+## Avoid extensive collaboration in user-owned repositories
+
+We recommend collaborating in organization-owned repositories whenever possible and minimizing collaboration in user-owned repositories. Organization-owned repositories have more sophisticated security and administrative features, and they remain accessible even as enterprise membership changes.
+
+## Use human-readable usernames
+
+{% ifversion ghec %}If you control the usernames for enterprise members, use{% else %}Use{% endif %} human-readable usernames, and avoid machine-generated IDs that are difficult for humans to read.
+
+You can manage the display of usernames within your enterprise's private repositories. For more information, see "[Managing the display of member names in your organization](/organizations/managing-organization-settings/managing-the-display-of-member-names-in-your-organization)."
+
+## Further reading
+
+- "[Best practices for repositories](/repositories/creating-and-managing-repositories/best-practices-for-repositories)"
+- "[Best practices for organizations](/organizations/collaborating-with-groups-in-organizations/best-practices-for-organizations)"

content/admin/overview/index.md

@@ -16,6 +16,7 @@ children:
   - /about-enterprise-accounts
   - /system-overview
   - /about-the-github-enterprise-api
+  - /best-practices-for-enterprises
   - /creating-an-enterprise-account
   - /accessing-compliance-reports-for-your-enterprise
 ---

content/code-security/security-overview/about-the-security-overview.md

@@ -28,7 +28,7 @@ shortTitle: About the security overview
 
 ## About the security overview
 
-The security overview provides high-level summaries of the security status of an organization or enterprise and make it easy to identify problematic repositories that require intervention. You can also use the security overview to see which repositories have enabled specific security features and to configure any available security features that are not currently in use. {% ifversion fpt %}For more information, see [the {% data variables.product.prodname_ghe_cloud %} documentation](/enterprise-cloud@latest/code-security/security-overview/about-the-security-overview).{% endif %}
+{% data reusables.security-overview.about-the-security-overview %} {% ifversion fpt %}For more information, see [the {% data variables.product.prodname_ghe_cloud %} documentation](/enterprise-cloud@latest/code-security/security-overview/about-the-security-overview).{% endif %}
 
 {% ifversion ghec or ghes or ghae %}
 The security overview shows which security features are enabled for repositories and consolidate alerts for each feature. 

content/get-started/onboarding/getting-started-with-github-enterprise-cloud.md

@@ -205,6 +205,8 @@ Members of your organization or enterprise can use GitHub's learning and support
 ### 1. Reading about {% data variables.product.prodname_ghe_cloud %} on {% data variables.product.prodname_docs %}
 You can read documentation that reflects the features available with {% data variables.product.prodname_ghe_cloud %}. For more information, see "[About versions of {% data variables.product.prodname_docs %}](/get-started/learning-about-github/about-versions-of-github-docs)."
 
+{% data reusables.enterprise.best-practices %}
+
 ### 2. Learning with {% data variables.product.prodname_learning %}
 Members of your organization or enterprise can learn new skills by completing fun, realistic projects in your very own GitHub repository with [{% data variables.product.prodname_learning %}](https://skills.github.com/). Each course is a hands-on lesson created by the GitHub community and taught by a friendly bot.
 

content/get-started/onboarding/getting-started-with-github-enterprise-server.md

@@ -119,6 +119,8 @@ Your enterprise members can learn more about Git and {% data variables.product.p
 
 You can read documentation that reflects the features available with {% data variables.product.prodname_ghe_server %}. For more information, see "[About versions of {% data variables.product.prodname_docs %}](/get-started/learning-about-github/about-versions-of-github-docs)."
 
+{% data reusables.enterprise.best-practices %}
+
 ### 2. Learning with {% data variables.product.prodname_learning %}
 {% data reusables.getting-started.learning-enterprise %}
 

content/get-started/signing-up-for-github/setting-up-a-trial-of-github-enterprise-cloud.md

@@ -62,6 +62,8 @@ After you set up your trial, you can explore {% data variables.product.prodname_
 
 {% data reusables.docs.you-can-read-docs-for-your-product %}
 
+{% data reusables.enterprise.best-practices %}
+
 {% data reusables.products.product-roadmap %}
 
 ## Finishing your trial

content/get-started/signing-up-for-github/setting-up-a-trial-of-github-enterprise-server.md

@@ -55,6 +55,8 @@ To get the most out of your trial, follow these steps:
 
     {% endnote %}
 
+{% data reusables.enterprise.best-practices %}    
+
 {% data reusables.products.product-roadmap %}
 
 ## Finishing your trial

content/organizations/collaborating-with-groups-in-organizations/about-organizations.md

@@ -28,7 +28,7 @@ You can configure the organization to meet the unique needs of your group by man
 
 To harden your organization's security, you can enforce security requirements and review the organization's audit log. For more information, see "[Keeping your organization secure](/organizations/keeping-your-organization-secure)."
 
-{% data reusables.organizations.org-ownership-recommendation %} 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)."
+To learn how to use organizations most effectively, see "[Best practices for organizations](/organizations/collaborating-with-groups-in-organizations/best-practices-for-organizations)."
 
 {% ifversion fpt or ghec %}
 ## About feature availability

content/organizations/collaborating-with-groups-in-organizations/best-practices-for-organizations.md

@@ -0,0 +1,35 @@
+---
+title: Best practices for organizations
+shortTitle: Best practices
+intro: Learn {% data variables.product.prodname_dotcom %}-recommended practices for your organization.
+versions:
+  fpt: '*'
+  ghes: '*'
+  ghae: '*'
+  ghec: '*'
+topics:
+  - Organizations
+  - Teams
+---
+
+## Assign multiple owners
+
+{% data reusables.organizations.org-ownership-recommendation %} 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)."
+
+## Use teams
+
+We recommend using teams to facilitate collaboration in your organization. For more information, see "[About teams](/organizations/organizing-members-into-teams/about-teams)."
+
+{% ifversion ghec %}
+We highly recommend managing team membership through your identity provider (IdP). For more information, see "[Managing team synchronization for your organization](/organizations/managing-saml-single-sign-on-for-your-organization/managing-team-synchronization-for-your-organization)."
+
+{% data reusables.enterprise-accounts.emu-scim-note %}
+{% endif %}
+
+We recommend keeping teams visible whenever possible and reserving secret teams for sensitive situations. For more information, see "[Changing team visibility](/organizations/organizing-members-into-teams/changing-team-visibility)."
+
+{% ifversion ghec or ghes or ghae %}
+## Use the security overview
+
+{% data reusables.security-overview.about-the-security-overview %} For more information, see "[About the security overview](/code-security/security-overview/about-the-security-overview)."
+{% endif %}

content/organizations/collaborating-with-groups-in-organizations/index.md

@@ -16,6 +16,7 @@ topics:
 children:
   - /about-organizations
   - /about-your-organization-dashboard
+  - /best-practices-for-organizations
   - /creating-a-new-organization-from-scratch
   - /accessing-your-organizations-settings
   - /customizing-your-organizations-profile

content/repositories/creating-and-managing-repositories/about-repositories.md

@@ -42,6 +42,8 @@ You can use repositories to manage your work and collaborate with others.
 
 {% data reusables.repositories.repo-size-limit %}
 
+To learn how to use repositories most effectively, see "[Best practices for repositories](/repositories/creating-and-managing-repositories/best-practices-for-repositories)."
+
 ## About repository visibility
 
 You can restrict who has access to a repository by choosing a repository's visibility: {% ifversion ghes or ghec %}public, internal, or private{% elsif ghae %}private or internal{% else %} public or private{% endif %}.
@@ -138,7 +140,6 @@ The compare view and pull requests pages display a list of commits between the `
 
 ## Further reading
 
-- "[Creating a new repository](/articles/creating-a-new-repository)"
 - "[About forks](/github/collaborating-with-pull-requests/working-with-forks/about-forks)"
 - "[Collaborating with issues and pull requests](/categories/collaborating-with-issues-and-pull-requests)"
 - "[Managing your work on {% data variables.product.prodname_dotcom %}](/categories/managing-your-work-on-github/)"

content/repositories/creating-and-managing-repositories/best-practices-for-repositories.md

@@ -0,0 +1,30 @@
+---
+title: Best practices for repositories
+shortTitle: Best practices
+intro: Learn how to use repositories most effectively.
+versions:
+  fpt: '*'
+  ghes: '*'
+  ghae: '*'
+  ghec: '*'
+topics:
+  - Repositories
+---
+
+## Create a README file
+
+To make it easier for people to understand and navigate your work, we recommend that you create a README file for every repository. 
+
+{% data reusables.repositories.about-READMEs %} For more information, see "[About READMEs](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes)."
+
+## Favor branching over forking
+
+To streamline collaboration, we recommend that regular collaborators work from a single repository, creating pull requests between branches instead of between repositories. Forking is best suited for accepting contributions from people that are unaffiliated with a project, such as open-source contributors.
+
+To maintain quality of important branches, such as `main`, while using a branching workflow, you can use protected branches with required status checks and pull request reviews. For more information, see "[About protected branches](/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/about-protected-branches)."
+
+## Use {% data variables.large_files.product_name_long %}
+
+To optimize performance, {% data variables.location.product_location %} limits the sizes of files allowed in repositories. For more information, see "[About large files on {% data variables.product.prodname_dotcom %}](/repositories/working-with-files/managing-large-files/about-large-files-on-github)."
+
+To track large files in a Git repository, we recommend using {% data variables.large_files.product_name_long %} ({% data variables.large_files.product_name_short %}). For more information, see "[About {% data variables.large_files.product_name_long %}](/repositories/working-with-files/managing-large-files/about-git-large-file-storage)."

content/repositories/creating-and-managing-repositories/index.md

@@ -13,6 +13,7 @@ topics:
   - Repositories
 children:
   - /about-repositories
+  - /best-practices-for-repositories
   - /creating-a-new-repository
   - /creating-a-repository-from-a-template
   - /creating-a-template-repository

content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes.md

@@ -17,7 +17,7 @@ topics:
 ---
 ## About READMEs
 
-You can add a README file to a repository to communicate important information about your project. A README, along with a repository license, citation file{% ifversion fpt or ghec %}, contribution guidelines, and a code of conduct{% elsif ghes %} and contribution guidelines{% endif %}, communicates expectations for your project and helps you manage contributions.
+{% data reusables.repositories.about-READMEs %}
 
 For more information about providing guidelines for your project, see {% ifversion fpt or ghec %}"[Adding a code of conduct to your project](/communities/setting-up-your-project-for-healthy-contributions/adding-a-code-of-conduct-to-your-project)" and {% endif %}"[Setting up your project for healthy contributions](/communities/setting-up-your-project-for-healthy-contributions)."
 

data/reusables/enterprise/best-practices.md

@@ -0,0 +1 @@
+To learn how your enterprise can use {% data variables.product.product_name %} most effectively, see "[Best practices for enterprises](/admin/overview/best-practices-for-enterprises)."

data/reusables/enterprise/ghec-authentication-options.md

@@ -0,0 +1 @@
+You can choose to allow members to create and manage user accounts, or your enterprise can create and manage accounts for members with {% data variables.product.prodname_emus %}. If you allow members to manage their own accounts, you can also configure SAML authentication to both increase security and centralize identity and access for the web applications that your team uses.

data/reusables/organizations/org-ownership-recommendation.md

@@ -1 +1 @@
-Projects maintained and managed by one sole organization owner can easily become inaccessible if the organization owner is unreachable. We recommend an organization have at least two people with *owner* permissions to ensure no one will lose access to a project.
+If an organization only has one owner, the organization's projects can become inaccessible if the owner is unreachable. To ensure that no one will lose access to a project, we recommend that at least two people within each organization have the owner role.

data/reusables/repositories/about-READMEs.md

@@ -0,0 +1 @@
+You can add a README file to a repository to communicate important information about your project. A README, along with a repository license, citation file{% ifversion fpt or ghec %}, contribution guidelines, and a code of conduct{% elsif ghes %} and contribution guidelines{% endif %}, communicates expectations for your project and helps you manage contributions.

data/reusables/security-overview/about-the-security-overview.md

@@ -0,0 +1 @@
+The security overview provides high-level summaries of the security status of an organization or enterprise and make it easy to identify problematic repositories that require intervention. You can also use the security overview to see which repositories have enabled specific security features and to configure any available security features that are not currently in use.