Merge branch 'docs-import-index-edits' into 'master'

Revise the intro doc for project migration

See merge request gitlab-org/gitlab!61185

doc/user/project/import/index.md

@@ -5,49 +5,52 @@ group: Import
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
 ---
 
-# Migrating projects to a GitLab instance
-
-1. [From Bitbucket Cloud](bitbucket.md)
-1. [From Bitbucket Server (also known as Stash)](bitbucket_server.md)
-1. [From ClearCase](clearcase.md)
-1. [From CVS](cvs.md)
-1. [From FogBugz](fogbugz.md)
-1. [From GitHub.com or GitHub Enterprise](github.md)
-1. [From GitLab.com](gitlab_com.md)
-1. [From Gitea](gitea.md)
-1. [From Perforce](perforce.md)
-1. [From SVN](svn.md)
-1. [From TFVC](tfvc.md)
-1. [From repository by URL](repo_by_url.md)
-1. [By uploading a manifest file (AOSP)](manifest.md)
-1. [From Phabricator](phabricator.md)
-1. [From Jira (issues only)](jira.md)
-
-In addition to the specific migration documentation above, you can import any
-Git repository via HTTP from the New Project page. Be aware that if the
-repository is too large the import can timeout.
-
-There is also the option of [connecting your external repository to get CI/CD benefits](../../../ci/ci_cd_for_external_repos/index.md). **(PREMIUM)**
+# Migrate projects to a GitLab instance
+
+See these documents to migrate to GitLab:
+
+- [From Bitbucket Cloud](bitbucket.md)
+- [From Bitbucket Server (also known as Stash)](bitbucket_server.md)
+- [From ClearCase](clearcase.md)
+- [From CVS](cvs.md)
+- [From FogBugz](fogbugz.md)
+- [From GitHub.com or GitHub Enterprise](github.md)
+- [From GitLab.com](gitlab_com.md)
+- [From Gitea](gitea.md)
+- [From Perforce](perforce.md)
+- [From SVN](svn.md)
+- [From TFVC](tfvc.md)
+- [From repository by URL](repo_by_url.md)
+- [By uploading a manifest file (AOSP)](manifest.md)
+- [From Phabricator](phabricator.md)
+- [From Jira (issues only)](jira.md)
+
+You can also import any Git repository through HTTP from the **New Project** page. Note that if the
+repository is too large, the import can timeout.
+
+You can also [connect your external repository to get CI/CD benefits](../../../ci/ci_cd_for_external_repos/index.md). **(PREMIUM)**
 
 ## LFS authentication
 
 When importing a project that contains LFS objects, if the project has an [`.lfsconfig`](https://github.com/git-lfs/git-lfs/blob/master/docs/man/git-lfs-config.5.ronn)
 file with a URL host (`lfs.url`) different from the repository URL host, LFS files are not downloaded.
 
-## Migrating from self-managed GitLab to GitLab.com
+## Migrate from self-managed GitLab to GitLab.com
 
-If you only need to migrate Git repositories, you can [import each project by URL](repo_by_url.md). Issues and merge requests can't be imported.
-
-If you want to retain all metadata like issues and merge requests, you can use
-the [import/export feature](../settings/import_export.md) to export projects from self-managed GitLab and import those projects into GitLab.com.
-
-All GitLab user associations (such as comment author) will be changed to the user importing the project. For more information, please see [the import notes](../settings/import_export.md#important-notes).
-
-If you need to migrate all data over, you can leverage our [API](../../../api/README.md) to migrate from self-managed to GitLab.com.
-The order of assets to migrate from a self-managed instance to GitLab.com is the following:
+If you only need to migrate Git repositories, you can [import each project by URL](repo_by_url.md).
+However, you can't import issues and merge requests this way. To retain all metadata like issues and
+merge requests, use the [import/export feature](../settings/import_export.md)
+to export projects from self-managed GitLab and import those projects into GitLab.com. All GitLab
+user associations (such as comment author) are changed to the user importing the project. For more
+information, see [the import notes](../settings/import_export.md#important-notes).
 
 NOTE:
-When migrating to GitLab.com, users would need to be manually created unless [SCIM](../../../user/group/saml_sso/scim_setup.md) is going to be used. Creating users with the API is limited to self-managed instances as it requires administrator access.
+When migrating to GitLab.com, you must create users manually unless [SCIM](../../../user/group/saml_sso/scim_setup.md)
+will be used. Creating users with the API is limited to self-managed instances as it requires
+administrator access.
+
+To migrate all data from self-managed to GitLab.com, you can leverage the [API](../../../api/README.md).
+Migrate the assets in this order:
 
 1. [Groups](../../../api/groups.md)
 1. [Projects](../../../api/projects.md)
@@ -55,43 +58,43 @@ When migrating to GitLab.com, users would need to be manually created unless [SC
 
 Keep in mind the limitations of the [import/export feature](../settings/import_export.md#exported-contents).
 
-You will still need to migrate your Container Registry over a series of
-Docker pulls and pushes and re-run any CI pipelines to retrieve any build artifacts.
+You must still migrate your [Container Registry](../../packages/container_registry/)
+over a series of Docker pulls and pushes. Re-run any CI pipelines to retrieve any build artifacts.
 
-## Migrating from GitLab.com to self-managed GitLab
+## Migrate from GitLab.com to self-managed GitLab
 
-The process is essentially the same as for [migrating from self-managed GitLab to GitLab.com](#migrating-from-self-managed-gitlab-to-gitlabcom). The main difference is that users can be created on the self-managed GitLab instance by an administrator through the UI or the [users API](../../../api/users.md#user-creation).
+The process is essentially the same as [migrating from self-managed GitLab to GitLab.com](#migrate-from-self-managed-gitlab-to-gitlabcom).
+The main difference is that an administrator can create users on the self-managed GitLab instance
+through the UI or the [users API](../../../api/users.md#user-creation).
 
-## Migrating between two self-managed GitLab instances
+## Migrate between two self-managed GitLab instances
 
-The best method for migrating from one GitLab instance to another,
-perhaps from an old server to a new server for example, is to
-[back up the instance](../../../raketasks/backup_restore.md),
-then restore it on the new server.
+To migrate from an existing self-managed GitLab instance to a new self-managed GitLab instance, it's
+best to [back up](../../../raketasks/backup_restore.md)
+the existing instance and restore it on the new instance. For example, this is useful when migrating
+a self-managed instance from an old server to a new server.
 
-In the event of merging two GitLab instances together (for example, both instances have existing data on them and one can't be wiped),
-refer to the instructions in [Migrating from self-managed GitLab to GitLab.com](#migrating-from-self-managed-gitlab-to-gitlabcom).
+To instead merge two self-managed GitLab instances together, use the instructions in
+[Migrate from self-managed GitLab to GitLab.com](#migrate-from-self-managed-gitlab-to-gitlabcom).
+This method is useful when both self-managed instances have existing data that must be preserved.
 
-Additionally, you can migrate users using the [Users API](../../../api/users.md) with an administrator user.
+Also note that administrators can use the [Users API](../../../api/users.md)
+to migrate users.
 
 ## Project aliases **(PREMIUM SELF)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3264) in GitLab Premium 12.1.
 
-When migrating repositories to GitLab and they are being accessed by other systems,
-it's very useful to be able to access them using the same name especially when
-they are a lot. It reduces the risk of changing significant number of Git URLs in
-a large number of systems.
-
-GitLab provides a functionality to help with this. In GitLab, repositories are
-usually accessed with a namespace and project name. It is also possible to access
-them via a project alias. This feature is only available on Git over SSH.
+GitLab repositories are usually accessed with a namespace and a project name. When migrating
+frequently accessed repositories to GitLab, however, you can use project aliases to access those
+repositories with the original name. Accessing repositories through a project alias reduces the risk
+associated with migrating such repositories.
 
-A project alias can be only created via API and only by GitLab administrators.
-Follow the [Project Aliases API documentation](../../../api/project_aliases.md) for
-more details.
+This feature is only available on Git over SSH. Also, only GitLab administrators can create project
+aliases, and they can only do so through the API. For more information, see the
+[Project Aliases API documentation](../../../api/project_aliases.md).
 
-After an alias has been created for a project (such as an alias `gitlab` for the
-project `https://gitlab.com/gitlab-org/gitlab`), you can clone the repository
-with the alias (e.g `git clone git@gitlab.com:gitlab.git` instead of
-`git clone git@gitlab.com:gitlab-org/gitlab.git`).
+After an administrator creates an alias for a project, you can use the alias to clone the
+repository. For example, if an administrator creates the alias `gitlab` for the project
+`https://gitlab.com/gitlab-org/gitlab`, you can clone the project with
+`git clone git@gitlab.com:gitlab.git` instead of `git clone git@gitlab.com:gitlab-org/gitlab.git`.