diff --git a/README.md b/README.md
index 3c784cea864c34309cc3276fd98f1b7e4a63614b..8fee85197eedcbda5df25348d713b069aca9d88c 100644
--- a/README.md
+++ b/README.md
@@ -22,6 +22,7 @@ Take a look at [TL;DR](#tldr) to start using it immediatly.
 * [x] Start to write the commit message in one key press, commit also in one key press.
 * [x] Modify in line the content just before staging it.
 * [x] Move easily through hunks.
+* [x] Handle multiple git repositories within one vim instance.
 * [x] Add file to .gitignore file.
 * [ ] Chase all corner cases. Please remember that vimagit is at an early development stage. If you try vimagit and nothing is working, please don't throw it, fill an [issue](https://github.com/jreybert/vimagit/issues/new) on github :heart: !
 
@@ -59,7 +60,7 @@ This is the minimal required set of command you must know to start playing with
 
 #### :Magit
 
-Open magit buffer.
+Open magit buffer (see [details](#magitshow_magit)).
 
 #### Enter,\<CR\>
 
@@ -117,7 +118,9 @@ Visual selection and marked lines have some limitations for the moment:
 
 #### magit#show_magit()
 
-Function to open magit buffer.
+Function to open magit buffer. This buffer will handle the git repository including focused file.
+It is possible to handle multiple git repositories within one vim instance.
+
 It takes 3 parameters:
   * orientation (mandatory): it can be
       - 'v', curent window is split vertically, and magit is displayed in new
@@ -131,10 +134,10 @@ It takes 3 parameters:
     (see [g:magit_default_fold_level](#gmagit_default_fold_level))
 
 #### :Magit
-open magit buffer in a vertical split
+Open magit buffer in a vertical split (see [details](magitshow_magit)).
 
 #### :MagitOnly
-open magit buffer in current window
+Open magit buffer in current window (see [details](magitshow_magit)).
 
 You can create a bash alias like magit="vim -c MagitOnly"
 
diff --git a/doc/vimagit.txt b/doc/vimagit.txt
index de2de0bc5e12475abe1b9ff0295e931ce75f15cd..7a4ba8f682b79b5c511249990f7e69595fe82853 100644
--- a/doc/vimagit.txt
+++ b/doc/vimagit.txt
@@ -50,7 +50,7 @@ with vimagit. See |vimagit-commands| for a complete description.
   :Magit
 -----------
 
-Open magit buffer.
+Open magit buffer (see |magit#show_magit()|)
 
   Enter
 -----------
@@ -131,7 +131,11 @@ Visual selection and marked lines have some limitations for the moment:
 COMMANDS                                                      *vimagit-commands*
 
                                                             *magit#show_magit()*
-Function to open magit buffer.
+Function to open magit buffer. This buffer will handle the git repository
+including focused file.
+It is possible to handle multiple git repositories within one vim instance.
+Each git repository will have its own buffer.
+
 It takes 3 parameters:
   * orientation (mandatory): it can be
       - 'v', curent window is split vertically, and magit is displayed in new
@@ -144,11 +148,11 @@ It takes 3 parameters:
   * foldlevel: set default magit buffer foldlevel for this session
     (see |vimagit-g:magit_default_fold_level|)
 
-                                                                         *:Magit*
-  :Magit     open magit buffer in a vertical split
+                                                                        *:Magit*
+  :Magit     open magit buffer in a vertical split (see |magit#show_magit()|)
 
-                                                                     *:MagitOnly*
-  :MagitOnly open magit buffer in current window
+                                                                    *:MagitOnly*
+  :MagitOnly open magit buffer in current window (see |magit#show_magit()|)
 You can create a bash alias like magit="vim -c MagitOnly"