Refactor GitHub import raketask docs

1 files changed, 18 insertions, 36 deletions

diff --git a/doc/administration/raketasks/github_import.md b/doc/administration/raketasks/github_import.md
index 93cfa56ec5b..ccd9c0afb1d 100644
--- a/doc/administration/raketasks/github_import.md
+++ b/doc/administration/raketasks/github_import.md
@@ -1,59 +1,41 @@
 # GitHub import
 
->**Note:**
->
->  - [Introduced][ce-10308] in GitLab 9.1.
->  - You need a personal access token in order to retrieve and import GitHub
->    projects. You can get it from: https://github.com/settings/tokens
->  - You also need to pass an username as the second argument to the rake task
->    which will become the owner of the project.
->  - You can also resume an import with the same command.
+>  [Introduced]( https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10308) in GitLab 9.1.
+
+In order to retrieve and import GitHub repositories, you will need a
+[GitHub personal access token](https://github.com/settings/tokens).
+A username should be passed as the second argument to the rake task
+which will become the owner of the project. You can resume an import
+with the same command.
+
+Bear in mind that the syntax is very specific. Remove any spaces within the argument block and
+before/after the brackets. Also, Some shells (e.g., zsh) can interpret the open/close brackets
+(`[]`) separately. You may need to either escape the brackets or use double quotes.
+
+## Importing multiple projects
 
 To import a project from the list of your GitHub projects available:
 
 ```bash
 # Omnibus installations
-sudo gitlab-rake import:github[access_token,root,foo/bar]
+sudo gitlab-rake "import:github[access_token,root,foo/bar]"
 
 # Installations from source
-bundle exec rake import:github[access_token,root,foo/bar] RAILS_ENV=production
+bundle exec rake "import:github[access_token,root,foo/bar]" RAILS_ENV=production
 ```
 
 In this case, `access_token` is your GitHub personal access token, `root`
 is your GitLab username, and  `foo/bar` is the new GitLab namespace/project that
 will get created from your GitHub project. Subgroups are also possible: `foo/foo/bar`.
 
+## Importing a single project
 
 To import a specific GitHub project (named `foo/github_repo` here):
 
 ```bash
 # Omnibus installations
-sudo gitlab-rake import:github[access_token,root,foo/bar,foo/github_repo]
+sudo gitlab-rake "import:github[access_token,root,foo/bar,foo/github_repo]"
 
 # Installations from source
-bundle exec rake import:github[access_token,root,foo/bar,foo/github_repo] RAILS_ENV=production
-```
-
-[ce-10308]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10308
-
-
-
-## Troubleshooting
-
-* Syntax is very specific. Remove spaces within argument block and prior to brackets
-
-```
-# Success
-sudo gitlab-rake import:github[access_token,root,foo/bar]
-
-# Fail
-sudo gitlab-rake import:github[access_token, root, foo/bar]
-rake aborted!
-Don't know how to build task 'import:github[access_token, root, foo/bar,' (see --tasks)
-```
-
-* Some shells can interpret the open/close brackets (`[]`) separately (ex: zsh). You may need to escape the brackets or switch shells
-
-```
-zsh: no matches found: import:github[token,root,foo/project,group/repository]
+bundle exec rake "import:github[access_token,root,foo/bar,foo/github_repo]" RAILS_ENV=production
 ```