Refactor audit events docs

doc/administration/audit_events.md

 # Audit Events
 
+> Introduced in [GitLab Enterprise Edition Premium][ee].
+
 GitLab Enterprise Edition offers a way to view the changes made within the
 GitLab server as a help to system administrators.
 
@@ -9,54 +11,82 @@ filesystem, see [the logs system documentation](logs.md) for more details.
 ## Overview
 
 **Audit Events** is a tool for GitLab Enterprise Edition administrators to be
-able to track important events such as user access level, target user, and user
-addition or removal.
+able to track important events such as who performed what action and the time
+it happened.
 
 ## Use-cases
 
-- You can use it to check who was the person who changed the permission level of
-a particular user for a project in your GitLab EE instance.
-- You can use it to track which users have access to certain group of projects
-in your GitLab instance, and who gave them that permission level.
+- Check who was the person who changed the permission level of a particular
+  user for a project in your GitLab EE instance.
+- Use it to track which users have access to a certain group of projects
+  in your GitLab instance, and who gave them that permission level.
+
+## List of events
+
+There are two kinds of events logged:
 
-## Security events
+- Events scoped to the group or project, used by group / project Owners
+  to loop up who made what change
+- Events scoped to the whole GitLab instance, used by the Compliance team to
+  perform formal audits
 
-| Security Event                 | Description                                                                                      |
-|--------------------------------|--------------------------------------------------------------------------------------------------|
-| User added to group or project | Notes the author of the change, target user                                                      |
-| User permission changed        | Notes the author of the change, original permission and new permission, target user              |
-| User login failed              | Notes the target username and IP address                                                         |
+### Group events
 
-## Audit events in project
+NOTE: **Note:**
+You need Owner [permissions] to view the Audit Events page.
 
-To view the Audit Events user needs to have enough permissions to view the project Settings page.
+To view a group's audit events, navigate to **Group > Settings > Audit Events**.
+From there, you can see the following actions:
 
-Navigate to **Project->Settings->Audit Events** to view the Audit Events:
+- Group created/deleted
+- Group changed visibility
+- User was added to group and with which [permissions]
+- Permissions changes of a user assigned to a group
+- Removed user from group
+- Project added to group and with which visibility level
+- Project removed from group
 
-![audit events project](audit_events_project.png)
+### Project events
 
-## Audit events in group
+NOTE: **Note:**
+You need Master [permissions] or higher to view the Audit Events page.
 
-To view the Audit Events user needs to have enough permissions to view the group Settings page.
+To view a project's audit events, navigate to **Project > Settings > Audit Events**.
+From there, you can see the following actions:
 
-Navigate to **Group->Settings->Audit Events** to view the Audit Events:
+- Added/removed deploy keys
+- Project created/deleted/renamed/moved(transferred)/changed path
+- Project changed visibility level
+- User was added to project and with which [permissions]
+- Permission changes of a user assigned to a project
+- User was removed from project
 
-![audit events group](audit_events_group.png)
+### Instance events
 
-## Audit Log (Admin only)
+> [Introduced][ee-2336] in [GitLab Enterprise Edition Premium][ee] 9.3.
+Available only for GitLab administrators.
 
-> **Notes:**
-> [Introduced][ee-2336] in GitLab 9.3.
+Server-wide audit logging introduces the ability to observe user actions across
+the entire instance of your GitLab server, making it easy to understand who
+changed what and when for audit purposes.
 
-Server-wide audit logging, available in GitLab Enterprise Edition Premium since 9.3, introduces
-the ability to observe user actions across the entire instance of your GitLab Server, making it
-easy to understand who changed what and when for audit purposes.
+To view the server-wide admin log, visit **Admin Area > Monitoring > Audit Log**.
+The following user actions are recorded:
 
-To view the server-wide admin log, visit the Admin Area, select Monitoring and choose Audit Log.
+- Failed Logins
+- Sign-in events and the authentication type (standard, LDAP, OmniAuth, etc.)
+- Added ssh key
+- Added/removed email
+- Changed password
+- Ask for password reset
+- Grant OAuth access
 
-It is possible to filter particular actions by choosing an audit data type from the filter drop-down.
-You can further filter by specific group, project or user (for authentication events).
+It is possible to filter particular actions by choosing an audit data type from
+the filter drop-down. You can further filter by specific group, project or user
+(for authentication events).
 
 ![audit log](audit_log.png)
 
 [ee-2336]: https://gitlab.com/gitlab-org/gitlab-ee/issues/2336
+[ee]: https://about.gitlab.com/gitlab-ee/
+[permissions]: ../user/permissions.md