diff --git a/doc/api/users.md b/doc/api/users.md
index a7e9518408c2f6ef215b1c4128affa99e44678e5..57078353fd0d84007d591790f13bf4927c35f45a 100644
--- a/doc/api/users.md
+++ b/doc/api/users.md
@@ -6,7 +6,7 @@ Get a list of users.
 
 This function takes pagination parameters `page` and `per_page` to restrict the list of users.
 
-### For normal users:
+### For normal users
 
 ```
 GET /users
@@ -31,8 +31,7 @@ GET /users
 ]
 ```
 
-
-### For admins: 
+### For admins
 
 ```
 GET /users
@@ -92,7 +91,7 @@ Also see `def search query` in `app/models/user.rb`.
 
 Get a single user.
 
-#### For user: 
+### For user
 
 ```
 GET /users/:id
@@ -112,8 +111,7 @@ Parameters:
 }
 ```
 
-
-#### For admin:
+### For admin
 
 ```
 GET /users/:id
@@ -161,13 +159,13 @@ Parameters:
 - `username` (required)         - Username
 - `name` (required)             - Name
 - `skype` (optional)            - Skype ID
-- `linkedin` (optional)         - Linkedin
+- `linkedin` (optional)         - LinkedIn
 - `twitter` (optional)          - Twitter account
-- `website_url` (optional)      - Website url
+- `website_url` (optional)      - Website URL
 - `projects_limit` (optional)   - Number of projects user can create
 - `extern_uid` (optional)       - External UID
 - `provider` (optional)         - External provider name
-- `bio` (optional)              - User's bio
+- `bio` (optional)              - User's biography
 - `admin` (optional)            - User is admin - true or false (default)
 - `can_create_group` (optional) - User can create groups - true or false
 
@@ -181,26 +179,32 @@ PUT /users/:id
 
 Parameters:
 
-- `email`                             - Email
-- `username`                          - Username
-- `name`                              - Name
-- `password`                          - Password
-- `skype`                             - Skype ID
-- `linkedin`                          - Linkedin
-- `twitter`                           - Twitter account
-- `website_url`                       - Website url
-- `projects_limit`                    - Limit projects each user can create
-- `extern_uid`                        - External UID
-- `provider`                          - External provider name
-- `bio`                               - User's bio
-- `admin` (optional)                  - User is admin - true or false (default)
-- `can_create_group` (optional)       - User can create groups - true or false
-
-Note, at the moment this method does only return a 404 error, even in cases where a 409 (Conflict) would be more appropriate, e.g. when renaming the email address to some existing one.
+- `email`                       - Email
+- `username`                    - Username
+- `name`                        - Name
+- `password`                    - Password
+- `skype`                       - Skype ID
+- `linkedin`                    - LinkedIn
+- `twitter`                     - Twitter account
+- `website_url`                 - Website URL
+- `projects_limit`              - Limit projects each user can create
+- `extern_uid`                  - External UID
+- `provider`                    - External provider name
+- `bio`                         - User's biography
+- `admin` (optional)            - User is admin - true or false (default)
+- `can_create_group` (optional) - User can create groups - true or false
+
+Note, at the moment this method does only return a 404 error,
+even in cases where a 409 (Conflict) would be more appropriate,
+e.g. when renaming the email address to some existing one.
 
 ## User deletion
 
-Deletes a user. Available only for administrators. This is an idempotent function, calling this function for a non-existent user id still returns a status code `200 Ok`. The JSON response differs if the user was actually deleted or not. In the former the user is returned and in the latter not.
+Deletes a user. Available only for administrators.
+This is an idempotent function, calling this function for a non-existent user id
+still returns a status code `200 Ok`.
+The JSON response differs if the user was actually deleted or not.
+In the former the user is returned and in the latter not.
 
 ```
 DELETE /users/:id
@@ -310,7 +314,7 @@ POST /user/keys
 Parameters:
 
 - `title` (required) - new SSH Key's title
-- `key` (required) - new SSH key
+- `key` (required)   - new SSH key
 
 ## Add SSH key for user
 
@@ -322,15 +326,17 @@ POST /users/:id/keys
 
 Parameters:
 
-- `id` (required) - id of specified user
+- `id` (required)    - id of specified user
 - `title` (required) - new SSH Key's title
-- `key` (required) - new SSH key
+- `key` (required)   - new SSH key
 
 Will return created key with status `201 Created` on success, or `404 Not found` on fail.
 
 ## Delete SSH key for current user
 
-Deletes key owned by currently authenticated user. This is an idempotent function and calling it on a key that is already deleted or not available results in `200 Ok`.
+Deletes key owned by currently authenticated user.
+This is an idempotent function and calling it on a key that is already deleted
+or not available results in `200 Ok`.
 
 ```
 DELETE /user/keys/:id
@@ -351,6 +357,6 @@ DELETE /users/:uid/keys/:id
 Parameters:
 
 - `uid` (required) - id of specified user
-- `id` (required) - SSH key ID
+- `id` (required)  - SSH key ID
 
 Will return `200 Ok` on success, or `404 Not found` if either user or key cannot be found.