Merge branch 'docs/add-overview-features-1' into 'master'

Add overview and use-cases to EE features

See merge request !2236

doc/administration/audit_events.md

 # Audit Events
 
-GitLab Enterprise Edition offers a way to view the changes made within the GitLab server as a help to system administrators.
+GitLab Enterprise Edition offers a way to view the changes made within the
+GitLab server as a help to system administrators.
 
-GitLab system administrators can also take advantage of the logs located on the filesystem, see [the logs system documentation](logs.md) for more details.
+GitLab system administrators can also take advantage of the logs located on the
+filesystem, see [the logs system documentation](logs.md) for more details.
 
+## Overview
 
-# Security Events
+**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.
+
+## 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.
+
+## Security events
 
 | 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              |
 
-
-# Audit Events in Project
+## Audit events in project
 
 To view the Audit Events user needs to have enough permissions to view the project Settings page.
 
-Navigate to Project->Settings->Audit Events to view the Audit Events:
+Navigate to **Project->Settings->Audit Events** to view the Audit Events:
 
 ![audit events project](audit_events_project.png)
 
-# Audit Events in Group
+## Audit events in group
 
 To view the Audit Events user needs to have enough permissions to view the group Settings page.
 
-Navigate to Group->Settings->Audit Events to view the Audit Events:
+Navigate to **Group->Settings->Audit Events** to view the Audit Events:
 
 ![audit events group](audit_events_group.png)
 
-# Audit Log (Admin only)
+## Audit Log (Admin only)
 
 > **Notes:**
 > [Introduced][ee-2336] in GitLab 9.3.

doc/administration/auth/ldap-ee.md

@@ -3,6 +3,26 @@
 This is a continuation of the main [LDAP documentation](ldap.md), detailing LDAP
 features specific to GitLab Enterprise Edition.
 
+## Overview
+
+[LDAP](https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol)
+stands for **Lightweight Directory Access Protocol**, which
+is a standard application protocol for
+accessing and maintaining distributed directory information services
+over an Internet Protocol (IP) network.
+
+GitLab integrates with LDAP to support **user authentication**. This integration
+works with most LDAP-compliant directory servers, including Microsoft Active
+Directory, Apple Open Directory, Open LDAP, and 389 Server.
+**GitLab Enterprise Edition** includes enhanced integration, including group
+membership syncing.
+
+## Use-cases
+
+- User Sync: Once a day, GitLab will update users against LDAP
+- Group Sync: Once an hour, GitLab will update group membership 
+based on LDAP group members
+
 ## User Sync
 
 Once per day, GitLab will run a worker to check and update GitLab

doc/analytics/contribution_analytics.md

-# Contribution Analytics (EE only)
+# Contribution Analytics
 
-_**Note:** This feature was introduced in GitLab EE 8.3._
+>**Note:**
+This feature was introduced in [GitLab Enterprise Edition Starter][ee] 8.3.
+
+Track your team members' activity across your organization.
+
+## Overview
 
 With contribution analytics you can have an overview for the activity of
 issues, merge requests and push events of your organization and its members.
@@ -8,25 +13,33 @@ issues, merge requests and push events of your organization and its members.
 The analytics page is located at **Group > Contribution Analytics**
 under the URL `/groups/<groupname>/analytics`.
 
-The time period on which the analytics depend on, is spanned in three sections:
-last week, last month and last three months. You can choose which one to
-display by using the dropdown calendar menu in the upper right corner.
+## Use-cases
 
-![Contribution analytics choose period](img/group_stats_cal.png)
+- Analyze your team's contributions along a period of time and offer a bonus
+  for the top contributors
+- If you are unhappy with a particular team member, you can use the analytics
+  as argument for demanding efficiency from this person
 
----
+## Using Contribution Analytics
 
 There are three main bar graphs that are deducted from the number of
 contributions per group member. These contributions include push events, merge
 requests and closed issues. Hovering on each bar you can see the number of
 events for a specific member.
 
-Below is an example of the push events of the
-[gitlab-org](https://gitlab.com/groups/gitlab-org/analytics) group.
-
 ![Contribution analytics bar graphs](img/group_stats_graph.png)
 
----
+## Changing the period time
+
+There are three periods you can choose from: 'Last week', 'Last month' and
+'Last three months'. The default is 'Last week'.
+
+You can choose which period to display by using the dropdown calendar menu in
+the upper right corner.
+
+![Contribution analytics choose period](img/group_stats_cal.png)
+
+## Sorting by different factors
 
 Apart from the bar graphs you can also see the contributions per group member
 which are depicted in a table that can be sorted by:
@@ -40,3 +53,5 @@ which are depicted in a table that can be sorted by:
 * Number of total contributions
 
 ![Contribution analytics contributions table](img/group_stats_table.png)
+
+[ee]: https://about.gitlab.com/gitlab-ee/

doc/gitlab-geo/README.md

@@ -31,6 +31,15 @@ Keep in mind that:
   clone/pull from repositories (HTTP(S)/SSH).
 - Primary talks to secondaries to notify for changes (API).
 
+## Use-cases
+
+- Can be used for cloning and fetching projects, in addition
+to reading any data
+- Overcomes slow connection between distant offices, saving time by
+improving speed for distributed teams
+- Helps reducing the loading time for automated tasks,
+custom integrations and internal workflows
+
 ## Architecture
 
 The following diagram illustrates the underlying architecture of GitLab Geo:

doc/integration/kerberos.md

 # Kerberos integration
 
-GitLab can be configured to allow your users to sign with their Kerberos credentials.
+>**Note:**
+Available in [GitLab Enterprise Edition Starter][ee].
+
+GitLab can integrate with [Kerberos][kerb] as an authentication mechanism.
+
+## Overview
+
+[Kerberos][kerb] is a secure method for authenticating a request for a service in a
+computer network. Kerberos was developed in the Athena Project at the
+[Massachusetts Institute of Technology (MIT)][mit]. The name is taken from Greek
+mythology; Kerberos was a three-headed dog who guarded the gates of Hades.
+
+## Use-cases
+
+- GitLab can be configured to allow your users to sign with their Kerberos credentials.
+- You can use Kerberos to [prevent][why-kerb] anyone from intercepting or eavesdropping on the transmitted password.
 
 ## Configuration
 
@@ -227,3 +242,7 @@ to a larger value in [the NGINX configuration][nginx].
 [restart gitlab]: ../administration/restart_gitlab.md#installations-from-source
 [reconfigure gitlab]: ../administration/restart_gitlab.md#omnibus-gitlab-reconfigure
 [nginx]: http://nginx.org/en/docs/http/ngx_http_core_module.html#large_client_header_buffers
+[kerb]: https://web.mit.edu/kerberos/
+[mit]: http://web.mit.edu/
+[why-kerb]: http://web.mit.edu/sipb/doc/working/guide/guide/node20.html
+[ee]: https://about.gitlab.com/gitlab-ee/

doc/tools/email.md

 # Email from GitLab
 
+>**Note:**
+Available in [GitLab Enterprise Edition Starter][ee].
+
 As a GitLab administrator you can email GitLab users from within GitLab.
 
-In the administrator interface, go to `Users`. Here you will find the button to email users:
+## Overview
+
+GitLab provides a simple tool to email all users or users of a chosen group or
+project right from the admin area. Users will receive the email to their primary
+email address.
+
+## Use-cases
 
-![admin users](email1.png)
+- Notify your users about a new project, a new feature, or a new product launch.
+- Notify your users about a new deployment, or that will be downtime expected
+  for a particular reason.
 
-Here you can simply compose an email.
+## Sending emails to users from within GitLab
 
-![compose an email](email2.png)
+1. Go to the admin area using the wrench icon in the top right corner and
+   navigate to **Overview > Users > Send email to users**.
 
-Which will be sent to all users or users of a chosen group or project.
+    ![admin users](email1.png)
 
-![recipients](email3.png)
+1. Compose an email and choose where it will be sent (all users or users of a
+   chosen group or project):
 
-## Note
-User can choose to unsubscribe from receiving emails from GitLab by following the unsubscribe link from the email.
-Unsubscribing is unauthenticated in order to keep the simplicity of this feature.
+    ![compose an email](email2.png)
+
+## Unsubscribing from emails
+
+User can choose to unsubscribe from receiving emails from GitLab by following
+the unsubscribe link from the email. Unsubscribing is unauthenticated in order
+to keep the simplicity of this feature.
 
 On unsubscribe, user will receive an email notifying that unsubscribe happened.
-Endpoint that provides unsubscribe option is protected by request being rate-limited.
+The endpoint that provides the unsubscribe option is rate-limited.
+
+[ee]: https://about.gitlab.com/gitlab-ee/

doc/user/project/description_templates.md

@@ -22,6 +22,18 @@ Description templates must be written in [Markdown](../markdown.md) and stored
 in your project's repository under a directory named `.gitlab`. Only the
 templates of the default branch will be taken into account.
 
+## Use-cases
+
+- Add a template to be used in every issue for a specific project,
+giving instructions and guidelines, requiring for information specific to that subject.
+For example, if you have a project for tracking new blog posts, you can require the
+title, outlines, author name, author social media information, etc.
+- Following the previous example, you can make a template for every MR submitted
+with a new blog post, requiring information about the post date, frontmatter data,
+images guidelines, link to the related issue, reviewer name, etc.
+- You can also create issues and merge request templates for different
+stages of your workflow, e.g., feature proposal, feature improvement, bug report, etc.
+
 ## Creating issue templates
 
 Create a new Markdown (`.md`) file inside the `.gitlab/issue_templates/`

doc/user/project/file_lock.md

-# File Lock
+# File Locking
 
->**Note:**
-This feature was [introduced][ee-440] in GitLab EE 8.9.
+>**Notes:**
+- [Introduced][ee-440] in [GitLab Enterprise Edition Premium][ee] 8.9.
+- This feature needs to have a license with the "File Lock" option enabled. If
+  you are using Enterprise Edition Premium but you don't see the "Lock" button,
+  ask your GitLab administrator.
 
----
+File Locking helps you avoid merge conflicts and better manage your binary files.
+Lock any file or directory, make your changes, and then unlock it so another
+member of the team can edit it.
 
->**Note:**
-This feature needs to have a license with the "File Lock" option enabled. If
-you are using Enterprise Edition but you don't see the "Lock" button,
-ask your GitLab administrator. Check GitLab's [pricing page] for more information.
+## Overview
 
-GitLab gives you the ability to lock any file or directory in the repository tree
-reserving you the right to make changes to that file or directory. **Locking only
-works for the default branch you have set in the project's settings** (usually
-`master`).
+Working with multiple people on the same file can be a risk. Conflicts
+when merging a non-text file are hard to overcome and will require a lot
+of manual work to resolve. With GitLab Enterprise Edition Premium, File
+Locking helps you avoid merge conflicts and better manage your binary
+files by preventing everyone, except you, from modifying a specific file
+or entire directory.
+
+## Use-cases
 
 The file locking feature is useful in situations when:
 
@@ -21,6 +27,7 @@ The file locking feature is useful in situations when:
   conflicts.
 - Your repository contains binary files in which situation there is no easy
   way to tell the diff between yours and your colleagues' changes.
+- Prevent design assets from being overwritten.
 
 Locked directories are locked recursively, which means that everything that
 lies under them is also locked.
@@ -59,6 +66,10 @@ is locked.
 
 ## Locking a file or a directory
 
+>**Note:**
+Locking only works for the default branch you have set in the project's settings
+(usually `master`).
+
 To lock a file, navigate to the repository tree under the **Repository > Files** tab,
 pick the file you want to lock and hit the "Lock" button.
 
@@ -92,5 +103,5 @@ locks and [remove the ones you have permission for](#permissions-on-file-locking
 ![Locked Files](img/file_lock_list.png)
 
 [ee-440]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/440 "File Lock"
-[pricing page]: https://about.gitlab.com/pricing
+[ee]: https://about.gitlab.com/gitlab-ee/
 [push access]: ../../user/permissions.md

doc/user/project/integrations/webhooks.md

@@ -11,12 +11,37 @@ a new issue is created. You can configure webhooks to listen for specific events
 like pushes, issues or merge requests. GitLab will send a POST request with data
 to the webhook URL.
 
+In most cases, you'll need to setup your own [webhook receiver](#example-webhook-receiver)
+to receive information from GitLab, and send it to another app, according to your needs.
+We already have a [built-in receiver](http://docs.gitlab.com/ce/project_services/slack.html)
+for sending [Slack](https://api.slack.com/incoming-webhooks) notifications _per project_.
+
+## Overview
+
+[Webhooks](https://en.wikipedia.org/wiki/Webhook) are "_user-defined HTTP
+callbacks_". They are usually triggered by some
+event, such as pushing code to a repository or a comment being posted to a blog.
+When that event occurs, the source app makes an HTTP request to the URI
+configured for the webhook. The action taken may be anything.
+Common uses are to trigger builds with continuous integration systems or to
+notify bug tracking systems.
+
 Webhooks can be used to update an external issue tracker, trigger CI jobs,
 update a backup mirror, or even deploy to your production server.
+They are available **per project** for GitLab Community Edition,
+and **per project and per group** for **GitLab Enterprise Edition**.
 
 Navigate to the webhooks page by going to your project's
 **Settings ➔ Integrations**.
 
+## Use-cases
+
+- You can setup a webhook in GitLab to send a notification to
+[Slack](https://api.slack.com/incoming-webhooks) every time a build fails, for example
+- You can [integrate with Twilio to be notified via SMS](https://www.datadoghq.com/blog/send-alerts-sms-customizable-webhooks-twilio/)
+every time an issue is created for a specific project or group within GitLab
+- You can use them to [automatically assign labels to merge requests](https://about.gitlab.com/2016/08/19/applying-gitlab-labels-automatically/).
+
 ## Webhook endpoint tips
 
 If you are writing your own endpoint (web server) that will receive

doc/workflow/repository_mirroring.md

@@ -2,14 +2,25 @@
 
 >[Introduced][ee-51] in GitLab Enterprise Edition 8.2.
 
+Repository Mirroring is a way to mirror repositories from external sources.
+It can be used to mirror all branches, tags, and commits that you have
+in your repository.
+
+Your mirror at GitLab will be updated automatically once an hour, but you can
+also manually update it whenever you need.
+
+## Overview
+
+Repository mirroring is very useful when, for some reason, you must use a
+project from another source.
+
 There are two kinds of repository mirroring features supported by GitLab:
 **push** and **pull**. The **push** method mirrors the repository in GitLab
 to another location, whereas the **pull** method mirrors an external repository
 in one in GitLab.
 
-By default mirror repositories are updated every hour, and all new branches, tags, and
-commits will be visible in the project's activity feed.
-
+By default, mirror repositories are updated every hour, and all new branches,
+tags, and commits will be visible in the project's activity feed.
 Users with at least [developer access][perms] to the project can also force an
 immediate update with a click of a button.
 
@@ -25,6 +36,17 @@ A few things/limitations to consider:
 - The Git LFS objects will not be synced. You'll need to push/pull them
   manually.
 
+## Use-cases
+
+- You migrated to GitLab but still need to keep you project in another source.
+  In that case, you can simply set it up to mirror to GitLab (pull) and all the
+  essential history of commits, tags and branches will be available in your
+  GitLab instance.
+- You have old projects in another source that you don't use actively anymore,
+  but don't want to remove for archiving purposes. In that case, you can create
+  a push mirror so that your active GitLab repository can push its changes to the
+  old location.
+
 ## Pulling from a remote repository
 
 You can set up a repository to automatically have its branches, tags, and commits