1 files changed, 77 insertions, 13 deletions
diff --git a/doc/workflow/add-user/add-user.md b/doc/workflow/add-user/add-user.md
index 8c9b4f72631..fffa0aba57f 100644
--- a/doc/workflow/add-user/add-user.md
+++ b/doc/workflow/add-user/add-user.md
@@ -1,25 +1,89 @@
 # Project users
 
-You can manage the groups and users and their access levels in all of your projects. You can also personalize the access level you give each user, per project.
+You can manage the groups and users and their access levels in all of your
+projects. You can also personalize the access level you give each user,
+per-project.
 
-Here's how to add or import users to your projects.
-
-You should have 'master' or 'owner' permissions to add or import a new user
+You should have `master` or `owner` permissions to add or import a new user
 to your project.
 
-To add or import a user, go to your project and click on "Members" on the left side of your screen:
+The first step to add or import a user, go to your project and click on
+**Members** on the left side of your screen.
+
+![Members](img/add_user_members_menu.png)
+
+---
+
+## Add a user
+
+Right next to **People**, start typing the name or username of the user you
+want to add.
+
+![Search for people](img/add_user_search_people.png)
+
+---
+
+Select the user and the [permission level](../../permissions/permissions.md)
+that you'd like to give the user. Note that you can select more than one user.
+
+![Give user permissions](img/add_user_give_permissions.png)
+
+---
+
+Once done, hit **Add users to project** and they will be immediately added to
+your project with the permissions you gave them above.
+
+![List members](img/add_user_list_members.png)
+
+---
+
+From there on, you can either remove an existing user or change their access
+level to the project.
+
+## Import users from another project
+
+You can import another project's users in your own project by hitting the
+**Import members** button on the upper right corner of the **Members** menu.
+
+In the dropdown menu, you can see only the projects you are Master on.
+
+![Import members from another project](img/add_user_import_members_from_another_project.png)
+
+---
+
+Select the one you want and hit **Import project members**. A flash message
+notifying you that the import was successful will appear, and the new members
+are now in the project's members list. Notice that the permissions that they
+had on the project you imported from are retained.
+
+![Members list of new members](img/add_user_imported_members.png)
+
+---
+
+## Invite people using their e-mail address
+
+If a user you want to give access to doesn't have an account on your GitLab
+instance, you can invite them just by typing their e-mail address in the
+user search field.
+
+![Invite user by mail](img/add_user_email_search.png)
+
+---
 
-![Members](images/members.png)
+As you can imagine, you can mix inviting multiple people and adding existing
+GitLab users to the project.
 
-Select "Add members" or "Import members" on the right side of your screen:
+![Invite user by mail ready to submit](img/add_user_email_ready.png)
 
-![Add or Import](images/add-members.png)
+---
 
-If you are adding a user, select the user and the [permission level](doc/permissions/permissions.md) that you'd like to
-give the user:
+Once done, hit **Add users to project** and watch that there is a new member
+with the e-mail address we used above. From there on, you can resend the
+invitation, change their access level or even delete them.
 
-![Add or Import](images/new-member.png)
+![Invite user members list](img/add_user_email_accept.png)
 
-If you are importing a user, follow the steps to select the project where you'd like to import the user from:
+---
 
-![Add or Import](images/select-project.png)
+Once the user accepts the invitation, they will be prompted to create a new
+GitLab account using the same e-mail address the invitation was sent to.