Merge branch 'doc_forking_refactor' into 'master'

Refactor forking workflow documentation

Closes #5974 

See merge request !2623

6 files changed, 41 insertions, 18 deletions

diff --git a/doc/workflow/forking/fork_button.png b/doc/workflow/forking/fork_button.png
deleted file mode 100644
index def4266476a..00000000000
--- a/doc/workflow/forking/fork_button.png
+++ /dev/null
diff --git a/doc/workflow/forking/groups.png b/doc/workflow/forking/groups.png
deleted file mode 100644
index 3ac64b3c8e7..00000000000
--- a/doc/workflow/forking/groups.png
+++ /dev/null
diff --git a/doc/workflow/forking_workflow.md b/doc/workflow/forking_workflow.md
index 8edf7c6ab3d..217a4a4012f 100644
--- a/doc/workflow/forking_workflow.md
+++ b/doc/workflow/forking_workflow.md
@@ -1,36 +1,59 @@
 # Project forking workflow
 
-Forking a project to your own namespace is useful if you have no write access to the project you want to contribute
-to. If you do have write access or can request it we recommend working together in the same repository since it is simpler.
-See our **[GitLab Flow](https://about.gitlab.com/2014/09/29/gitlab-flow/)** article for more information about using
-branches to work together.
+Forking a project to your own namespace is useful if you have no write
+access to the project you want to contribute to. If you do have write
+access or can request it, we recommend working together in the same
+repository since it is simpler. See our [GitLab Flow](gitlab_flow.md)
+document more information about using branches to work together.
 
 ## Creating a fork
 
-In order to create a fork of a project, all you need to do is click on the fork button located on the top right side
-of the screen, close to the project's URL and right next to the stars button.
+Forking a project is in most cases a two-step process.
 
-![Fork button](forking/fork_button.png)
 
-Once you do that you'll be presented with a screen where you can choose the namespace to fork to. Only namespaces
-(groups and your own namespace) where you have write access to, will be shown. Click on the namespace to create your
-fork there.
+1.  Click on the fork button located in the middle of the page or a project's
+    home page right next to the stars button.
 
-![Groups view](forking/groups.png)
+    ![Fork button](img/forking_workflow_fork_button.png)
 
-After the forking is done, you can start working on the newly created repository. There you will have full
-[Owner](../permissions/permissions.md) access, so you can set it up as you please.
+    ---
+
+1.  Once you do that, you'll be presented with a screen where you can choose
+    the namespace to fork to. Only namespaces (groups and your own
+    namespace) where you have write access to, will be shown. Click on the
+    namespace to create your fork there.
+
+    ![Choose namespace](img/forking_workflow_choose_namespace.png)
+
+    ---
+
+    **Note:**
+    If the namespace you chose to fork the project to has another project with
+    the same path name, you will be presented with a warning that the forking
+    could not be completed. Try to resolve the error and repeat the forking
+    process.
+
+    ![Path taken error](img/forking_workflow_path_taken_error.png)
+
+    ---
+
+After the forking is done, you can start working on the newly created
+repository. There, you will have full [Owner](../permissions/permissions.md)
+access, so you can set it up as you please.
 
 ## Merging upstream
 
-Once you are ready to send your code back to the main project, you need to create a merge request. Choose your forked
-project's main branch as the source and the original project's main branch as the destination and create the merge request.
+Once you are ready to send your code back to the main project, you need
+to create a merge request. Choose your forked project's main branch as
+the source and the original project's main branch as the destination and
+create the [merge request](merge_requests.md).
 
 ![Selecting branches](forking/branch_select.png)
 
-You can then assign the merge request to someone to have them review your changes. Upon pressing the 'Accept Merge Request'
-button, your changes will be added to the repository and branch you're merging into.
+You can then assign the merge request to someone to have them review
+your changes. Upon pressing the 'Accept Merge Request' button, your
+changes will be added to the repository and branch you're merging into.
 
 ![New merge request](forking/merge_request.png)
 
-
+[gitlab flow]: https://about.gitlab.com/2014/09/29/gitlab-flow/ "GitLab Flow blog post"
diff --git a/doc/workflow/img/forking_workflow_choose_namespace.png b/doc/workflow/img/forking_workflow_choose_namespace.png
new file mode 100644
index 00000000000..eefe5769554
--- /dev/null
+++ b/doc/workflow/img/forking_workflow_choose_namespace.png
diff --git a/doc/workflow/img/forking_workflow_fork_button.png b/doc/workflow/img/forking_workflow_fork_button.png
new file mode 100644
index 00000000000..49e68d33e89
--- /dev/null
+++ b/doc/workflow/img/forking_workflow_fork_button.png
diff --git a/doc/workflow/img/forking_workflow_path_taken_error.png b/doc/workflow/img/forking_workflow_path_taken_error.png
new file mode 100644
index 00000000000..7a3139506fe
--- /dev/null
+++ b/doc/workflow/img/forking_workflow_path_taken_error.png