Refactor the SubGit/SVN documentation

[ci skip]

1 files changed, 52 insertions, 40 deletions

diff --git a/doc/workflow/importing/migrating_from_svn.md b/doc/workflow/importing/migrating_from_svn.md
index fc27a38f735..423b095e69e 100644
--- a/doc/workflow/importing/migrating_from_svn.md
+++ b/doc/workflow/importing/migrating_from_svn.md
@@ -10,7 +10,7 @@ There are two approaches to SVN to Git migration:
 
 1. [Git/SVN Mirror](#smooth-migration-with-a-gitsvn-mirror-using-subgit) which:
     - Makes the GitLab repository to mirror the SVN project.
-    - Git and SVN repositories are kept in sync; you can use either one.  
+    - Git and SVN repositories are kept in sync; you can use either one.
     - Smoothens the migration process and allows to manage migration risks.
 
 1. [Cut over migration](#cut-over-migration-with-svn2git) which:
@@ -19,82 +19,94 @@ There are two approaches to SVN to Git migration:
 
 ## Smooth migration with a Git/SVN mirror using SubGit
 
-#### Prerequisites
+[SubGit](https://subgit.com) is a tool for a smooth, stress-free SVN to Git
+migration. It creates a writable Git mirror of a local or remote Subversion
+repository and that way you can use both Subversion and Git as long as you like.
+It requires access to your GitLab server as it talks with the Git repositories
+directly in a filesystem level.
 
-Install Oracle JRE 1.8 or newer. On Debian-based Linux distributions follow this 
-[instruction](http://www.webupd8.org/2012/09/install-oracle-java-8-in-ubuntu-via-ppa.html).
+### SubGit prerequisites
 
-Download SubGit tool from [https://subgit.com/download/](https://subgit.com/download/)
+1. Install Oracle JRE 1.8 or newer. On Debian-based Linux distributions you can
+   follow [this article](http://www.webupd8.org/2012/09/install-oracle-java-8-in-ubuntu-via-ppa.html).
+1. Download SubGit from https://subgit.com/download/.
+1. Unpack the downloaded SubGit zip archive to the `/opt` directory. The `subgit`
+   command will be available at `/opt/subgit-VERSION/bin/subgit`.
 
-Unpack downloaded SubGit zip archive to `/opt` directory, subgit will be available
-at `/opt/subgit-VERSION/bin/subgit`
+### SubGit configuration
 
-#### Configuration
-
-In GitLab create new empty repository. In filesystem it will be located at 
-`/var/opt/gitlab/git-data/repositories/USER/REPOS.git` path by default. 
-For convenice, assign this path to a variable:
+The first step to mirror you SVN repository in GitLab is to create a new empty
+project which will be used as a mirror. For Omnibus installations the path to
+the repository will be located at
+`/var/opt/gitlab/git-data/repositories/USER/REPO.git` by default. For
+installations from source, the default repository directory will be
+`/home/git/repositories/USER/REPO.git`. For convenience, assign this path to a
+variable:
 
 ```
-GIT_REPOS_PATH=/var/opt/gitlab/git-data/repositories/USER/REPOS.git
+GIT_REPO_PATH=/var/opt/gitlab/git-data/repositories/USER/REPOS.git
 ```
 
-SubGit will keep this repository will be kept in sync with a remote SVN project.
-For convenience, assign remote SVN project URL to a variable:
+SubGit will keep this repository in sync with a remote SVN project. For
+convenience, assign your remote SVN project URL to a variable:
 
 ```
 SVN_PROJECT_URL=http://svn.company.com/repos/project
 ```
 
-Run SubGit to set up a Git/SVN mirror. Make sure `subgit` command is ran
-on behalf of the same user that keeps ownership of GitLab Git repositories (`git` by default):
+Next you need to run SubGit to set up a Git/SVN mirror. Make sure the following
+`subgit` command is ran on behalf of the same user that keeps ownership of
+GitLab Git repositories (by default `git`):
 
 ```
-subgit configure --layout auto $SVN_PROJECT_URL $GIT_REPOS_PATH
+subgit configure --layout auto $SVN_PROJECT_URL $GIT_REPO_PATH
 ```
 
-Adjust authors and branches mappings, if necessary:
+Adjust authors and branches mappings, if necessary. Open with your favorite
+text editor:
 
 ```
-edit $GIT_REPOS_PATH/subgit/authors.txt
-edit $GIT_REPOS_PATH/subgit/config
+edit $GIT_REPO_PATH/subgit/authors.txt
+edit $GIT_REPO_PATH/subgit/config
 ```
 
-For more information regarding SubGit configuration options, refer to 
-[documentation](https://subgit.com/documentation.html) at SubGit web site.
+For more information regarding the SubGit configuration options, refer to
+[SubGit's documentation](https://subgit.com/documentation.html) website.
 
-#### Initial translation
+### Initial translation
 
-Run `subgit` to perform initial translation of existing SVN revisions into
-Git repository:
+Now that SubGit has configured the Git/SVN repos, run `subgit` to perform the
+initial translation of existing SVN revisions into the Git repository:
 
 ```
 subgit install $GIT_REPOS_PATH
 ```
 
-After initial translation is completed, GitLab Git repository and SVN project
-will be kept in sync by `subgit` - new Git commits will be translated to SVN
-revisions and new SVN revisions will be translated to Git commits. Mirror works
-transparently and does not require any special commands.
+After the initial translation is completed, the Git repository and the SVN
+project will be kept in sync by `subgit` - new Git commits will be translated to
+SVN revisions and new SVN revisions will be translated to Git commits. Mirror
+works transparently and does not require any special commands.
 
-Would you prefer to perform one-time cut over migration with `subgit` use 
-`import` command in place of `install`:
+If you would prefer to perform one-time cut over migration with `subgit`, use
+the `import` command instead of `install`:
 
 ```
-subgit import $GIT_REPOS_PATH
+subgit import $GIT_REPO_PATH
 ```
 
-#### Licensing
+### SubGit licensing
 
-Running SubGit in a mirror mode requires [registration](https://subgit.com/pricing.html). Registration is free for Open Source,
-Academic and Startup projects.
+Running SubGit in a mirror mode requires a
+[registration](https://subgit.com/pricing.html). Registration is free for open
+source, academic and startup projects.
 
-We're currently working on deeper GitLab/SubGit intergation. You may track our
+We're currently working on deeper GitLab/SubGit integration. You may track our
 progress at [this issue](https://gitlab.com/gitlab-org/gitlab-ee/issues/990).
 
-#### Support
+### SubGit support
 
-For any questions related to SVN to GitLab migration with SubGit you can contact SubGit team at [support@subgit.com](mailto:support@subgit.com).
+For any questions related to SVN to GitLab migration with SubGit, you can
+contact the SubGit team directly at [support@subgit.com](mailto:support@subgit.com).
 
 ## Cut over migration with svn2git
 
@@ -168,4 +180,4 @@ git push --tags origin
 
 ## Contribute to this guide
 We welcome all contributions that would expand this guide with instructions on
-how to migrate from SVN and other version control systems.
\ No newline at end of file
+how to migrate from SVN and other version control systems.