refactor ee-docs landing page

doc/README.md

 # GitLab Enterprise Edition
 
-All technical content published by GitLab lives in the documentation, including:
+[GitLab](https://about.gitlab.com/) is a Git-based fully featured platform for software development.
 
-- **General Documentation**
-  - [User docs](#user-documentation): general documentation dedicated to regular users of GitLab
-  - [Admin docs](#administrator-documentation): general documentation dedicated to administrators of GitLab instances
-  - [Contributor docs](#contributor-documentation): general documentation on how to develop and contribute to GitLab
-- [GitLab University](university/README.md): guides to learn Git and GitLab
-  through courses and videos.
+**[GitLab Enterprise Edition (EE)](https://about.gitlab.com/gitlab-ee/)** is an opencore product, self-hosted, available under distinct [subscriptions](https://about.gitlab.com/products/).
 
-## User documentation
+GitLab EE contains all the features available in [GitLab Community Edition (CE)](https://docs.gitlab.com/ce/), plus premium features available in each version: **Enterprise Edition Starter** (**EES**) and **Enterprise Edition Premium** (**EEP**). Everything available in **EES** is also available in **EEP**.
 
-- [Account Security](user/profile/account/two_factor_authentication.md) Securing your account via two-factor authentication, etc.
-- [API](api/README.md) Automate GitLab via a simple and powerful API.
-- [CI/CD](ci/README.md) GitLab Continuous Integration (CI) and Continuous Delivery (CD) getting started, `.gitlab-ci.yml` options, and examples.
-- [Container Registry](user/project/container_registry.md) Learn how to use GitLab Container Registry.
-- [Discussions](user/discussions/index.md) Threads, comments, and resolvable discussions in issues, commits, and  merge requests.
-- [Git Attributes](user/project/git_attributes.md) Managing Git attributes using a `.gitattributes` file.
-- [Git cheatsheet](https://gitlab.com/gitlab-com/marketing/raw/master/design/print/git-cheatsheet/print-pdf/git-cheatsheet.pdf) Download a PDF describing the most used Git operations.
-- [GitLab as OAuth2 authentication service provider](integration/oauth_provider.md). It allows you to login to other applications from GitLab.
-- [GitLab basics](gitlab-basics/README.md) Find step by step how to start working on your commandline and on GitLab.
-- [GitLab Pages](user/project/pages/index.md) Using GitLab Pages.
+----
+
+Shortcuts to GitLab's most visited docs:
+
+| [GitLab CI](ci/README.md) | Other |
+| :----- | :----- |
+| [Quick start guide](ci/quick_start/README.md) | [API](api/README.md) |
+| [Configuring `.gitlab-ci.yml`](ci/yaml/README.md) | [SSH authentication](ssh/README.md) |
+| [Using Docker images](ci/docker/using_docker_images.md) | [GitLab Pages](user/project/pages/index.md) |
+
+## Getting started with GitLab
+
+- [GitLab Basics](gitlab-basics/README.md): Start working on your command line and on GitLab.
+- [GitLab Workflow](workflow/README.md): Enhance your workflow with the best of GitLab Workflow.
+  - See also [GitLab Workflow - an overview](https://about.gitlab.com/2016/10/25/gitlab-workflow-an-overview/).
+- [GitLab Markdown](user/markdown.md): GitLab's advanced formatting system (GitLab Flavored Markdown).
+- [GitLab Slash Commands](user/project/slash_commands.md): Textual shortcuts for common actions on issues or merge requests that are usually done by clicking buttons or dropdowns in GitLab's UI
+
+### User account
+
+- [Authentication](topics/authentication/index.md): Account security with two-factor authentication, setup your ssh keys and deploy keys for secure access to your projects.
+- [Profile settings](profile/README.md): Manage your profile settings, two factor authentication and more.
+- [User permissions](user/permissions.md): Learn what each role in a project (external/guest/reporter/developer/master/owner) can do.
+
+### Projects and groups
+
+- [Create a project](gitlab-basics/create-project.md)
+- [Fork a project](gitlab-basics/fork-project.md)
 - [Importing and exporting projects between instances](user/project/settings/import_export.md).
-- [Importing to GitLab](workflow/importing/README.md) Import your projects from GitHub, Bitbucket, GitLab.com, FogBugz and SVN into GitLab.
-- [Markdown](user/markdown.md) GitLab's advanced formatting system.
-- [Migrating from SVN](workflow/importing/migrating_from_svn.md) Convert a SVN repository to Git and GitLab.
-- [Permissions](user/permissions.md) Learn what each role in a project (external/guest/reporter/developer/master/owner) can do.
-- [Profile Settings](profile/README.md)
-- [Project Services](user/project/integrations/project_services.md) Integrate a project with external services, such as CI and chat.
-- [Public access](public_access/public_access.md) Learn how you can allow public and internal access to projects.
-- [Analytics](analytics/README.md)
+- [Project access](public_access/public_access.md): Setting up your project's visibility to public, internal, or private.
+- [Groups](workflow/groups.md): Organize your projects in groups.
+  - [Create a group](gitlab-basics/create-group.md)
+  - [GitLab Subgroups](user/group/subgroups/index.md)
 - [Search through GitLab](user/search/index.md): Search for issues, merge requests, projects, groups, todos, and issues in Issue Boards.
-- [Snippets](user/snippets.md) Snippets allow you to create little bits of code.
-- [SSH](ssh/README.md) Setup your ssh keys and deploy keys for secure access to your projects.
-- [Webhooks](user/project/integrations/webhooks.md) Let GitLab notify you when new code has been pushed to your project.
-- [Workflow](workflow/README.md) Using GitLab functionality and importing projects from GitHub and SVN.
+
+### Repository
+
+Manage files and branches from the UI (user interface):
+
+- Files
+  - [Create a file](user/project/repository/web_editor.md#create-a-file)
+  - [Upload a file](user/project/repository/web_editor.md#upload-a-file)
+  - [File templates](user/project/repository/web_editor.md#template-dropdowns)
+  - [Create a directory](user/project/repository/web_editor.md#create-a-directory)
+  - [Start a merge request](user/project/repository/web_editor.md#tips) (when committing via UI)
+  - **(EES/EEP)** [Lock a file](user/project/file_lock.md): Lock a file to avoid merge conflicts.
+- Branches
+  - [Create a branch](user/project/repository/web_editor.md#create-a-new-branch)
+  - [Protected branches](user/project/protected_branches.md#protected-branches)
+- **(EES/EEP)** [Repository Mirroring](workflow/repository_mirroring.md)
+- **(EES/EEP)** [Push rules](push_rules/push_rules.md): Additional control over pushes to your project.
+
+### Issues and Merge Requests (MRs)
+
+- [Discussions](user/discussions/index.md) Threads, comments, and resolvable discussions in issues, commits, and  merge requests.
+- Issues
+  - [Create an issue](gitlab-basics/create-issue.md#how-to-create-an-issue-in-gitlab)
+  - [Confidential Issues](user/project/issues/confidential_issues.md)
+  - [Automatic issue closing](user/project/issues/automatic_issue_closing.md)
+  - [Issue Boards](user/project/issue_board.md)
+- [Issues and merge requests templates](user/project/description_templates.md): Create templates for submitting new issues and merge requests.
+- [Labels](user/project/labels.md): Categorize your issues or merge requests based on descriptive titles.
+- [Merge Requests](user/project/merge_requests/index.md)
+  - [WIP Merge Requests](user/project/merge_requests/work_in_progress_merge_requests.md)
+  - [Merge Request discussion resolution](user/discussions/index.md#moving-a-single-discussion-to-a-new-issue): Resolve discussions, move discussions in a merge request to an issue, only allow merge requests to be merged if all discussions are resolved.
+  - **(EES/EEP)** [Merge Request approval](user/project/merge_requests/merge_request_approvals.md): Make sure every merge request is approved by one or more people before getting merged.
+  - [Checkout merge requests locally](user/project/merge_requests/index.md#checkout-merge-requests-locally)
+  - [Cherry-pick](user/project/merge_requests/cherry_pick_changes.md)
+- [Milestones](user/project/milestones/index.md): Organize issues and merge requests into a cohesive group, optionally setting a due date.
+  - **(EES/EEP)** [Burndown Charts](user/project/milestones/index.md#burndown-charts): Watch your project's progress throughout a specific milestone.
+- [Todos](workflow/todos.md): A chronological list of to-dos that are waiting for your input, all in a simple dashboard.
+
+### Git and GitLab
+
+- [Git](topics/git/index.md): Getting started with Git, branching strategies, Git LFS, advanced use.
+- [Git cheatsheet](https://gitlab.com/gitlab-com/marketing/raw/master/design/print/git-cheatsheet/print-pdf/git-cheatsheet.pdf): Download a PDF describing the most used Git operations.
+- [GitLab Flow](workflow/gitlab_flow.md): explore the best of Git with the GitLab Flow strategy.
+
+### Migrate and import your projects from other platforms
+
+- [Importing to GitLab](workflow/importing/README.md): Import your projects from GitHub, Bitbucket, GitLab.com, FogBugz and SVN into GitLab.
+- [Migrating from SVN](workflow/importing/migrating_from_svn.md): Convert a SVN repository to Git and GitLab.
+
+## GitLab's superpowers
+
+Take a step ahead and dive into GitLab's advanced features.
+
+- **(EEP)** [GitLab Service Desk](user/project/service_desk.md): A simple way to allow people to create issues in your GitLab instance without needing their own user account.
+- **(EEP)** [File Locking](user/project/file_lock.md): Lock a file to avoid merge conflicts.
+- **(EES/EEP)** [Contribution Analytics](analytics/contribution_analytics.md): See detailed statistics of projects' contributors.
+- [GitLab Pages](user/project/pages/index.md): Build, test, and deploy your static website with GitLab Pages.
+- [Snippets](user/snippets.md): Snippets allow you to create little bits of code.
+- [Wikis](workflow/project_features.md#wiki): Enhance your repository documentation with built-in wikis.
+
+### Continuous Integration, Delivery, and Deployment
+
+- [GitLab CI](ci/README.md): Explore the features and capabilities of Continuous Integration, Continuous Delivery, and Continuous Deployment with GitLab.
+  - [Auto Deploy](ci/autodeploy/index.md): Configure GitLab CI for the deployment of your application.
+  - [Review Apps](ci/review_apps/index.md): Preview changes to your app right from a merge request.
+  - **(EEP)** [Deploy Boards](user/project/deploy_boards.md): View of the current health and status of each CI environment running on Kubernetes, displaying the status of the pods in the deployment.
+  - **(EEP)** [Canary Deployments](user/project/deploy_boards.md#canary-deployments): A popular CI strategy, where a small portion of the fleet is updated to the new version first.
+- [GitLab Cycle Analytics](user/project/cycle_analytics.md): Cycle Analytics measures the time it takes to go from an [idea to production](https://about.gitlab.com/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/#from-idea-to-production-with-gitlab) for each project you have.
+- [GitLab Container Registry](user/project/container_registry.md): Learn how to use GitLab's built-in Container Registry.
+
+### Automation
+
+- [API](api/README.md): Automate GitLab via a simple and powerful API.
+- [GitLab Webhooks](user/project/integrations/webhooks.md): Let GitLab notify you when new code has been pushed to your project.
+
+### Integrations
+
+- [Project Services](user/project/integrations/project_services.md): Integrate a project with external services, such as CI and chat.
+- [GitLab Integrations](integration/README.md): Integrate with multiple third-party services with GitLab to allow external issue trackers and external authentication.
+
+----
 
 ## Administrator documentation
 
+Learn how to administer your GitLab instance. Regular users don't
+have access to GitLab administration tools and settings.
+
+### Install, update, upgrade, migrate
+
+- [Install](install/README.md): Requirements, directory structures and installation from source.
+- [Mattermost](https://docs.gitlab.com/omnibus/gitlab-mattermost/): Integrate [Mattermost](https://about.mattermost.com/) with your GitLab installation.
+- [Migrate GitLab CI to CE/EE](migrate_ci_to_ce/README.md): If you have an old GitLab installation (older than 8.0), follow this guide to migrate your existing GitLab CI data to GitLab CE/EE.
+- [Restart GitLab](administration/restart_gitlab.md): Learn how to restart GitLab and its components.
+- [Update](update/README.md): Update guides to upgrade your installation.
 - [Upload your GitLab License](user/admin_area/license.md) Upload the license you purchased for GitLab Enterprise Edition to unlock its features.
-- [Audit Events](administration/audit_events.md) Check how user access changed in projects and groups.
-- [Access restrictions](user/admin_area/settings/visibility_and_access_controls.md#enabled-git-access-protocols) Define which Git access protocols can be used to talk to GitLab
-- [Authentication/Authorization](administration/auth/README.md) Configure external authentication with LDAP, SAML, CAS and additional Omniauth providers.
-- [Changing the appearance of the login page](customization/branded_login_page.md) Make the login page branded for your GitLab instance.
-- [Email](tools/email.md) Email GitLab users from GitLab
-- [Push Rules](push_rules/push_rules.md) Advanced push rules for your project.
-- [Help message](customization/help_message.md) Set information about administrators of your GitLab instance.
-- [Changing the appearance of the login page](customization/branded_login_page.md) Make the login page branded for your GitLab instance.
-- [Email](tools/email.md) Email GitLab users from GitLab
-- [Push Rules](push_rules/push_rules.md) Advanced push rules for your project.
-- [Help message](customization/help_message.md) Set information about administrators of your GitLab instance.
-- [Container Registry](administration/container_registry.md) Configure Docker Registry with GitLab.
-- [Custom Git hooks](administration/custom_hooks.md) Custom Git hooks (on the filesystem) for when webhooks aren't enough.
-- [Debugging Tips](administration/troubleshooting/debug.md) Tips to debug problems when things go wrong
-- [Environment Variables](administration/environment_variables.md) to configure GitLab.
-- [Git LFS configuration](workflow/lfs/lfs_administration.md)
-- [GitLab Pages configuration](administration/pages/index.md) Configure GitLab Pages.
-- [GitLab performance monitoring with InfluxDB](administration/monitoring/performance/introduction.md) Configure GitLab and InfluxDB for measuring performance metrics.
-- [GitLab performance monitoring with Prometheus](administration/monitoring/prometheus/index.md) Configure GitLab and Prometheus for measuring performance metrics.
-- [Header logo](customization/branded_page_and_email_header.md) Change the logo on the overall page and email header.
-- [High Availability](administration/high_availability/README.md) Configure multiple servers for scaling or high availability.
-- [Housekeeping](administration/housekeeping.md) Keep your Git repository tidy and fast.
-- [Install](install/README.md) Requirements, directory structures and installation from source.
-- [Integration](integration/README.md) How to integrate with systems such as JIRA, Redmine, Twitter.
-- [Issue closing pattern](administration/issue_closing_pattern.md) Customize how to close an issue from commit messages.
-- [Koding](administration/integration/koding.md) Set up Koding to use with GitLab.
-- [Libravatar](customization/libravatar.md) Use Libravatar instead of Gravatar for user avatars.
-- [Log system](administration/logs.md) Log system.
-- [Migrate GitLab CI to CE/EE](migrate_ci_to_ce/README.md) Follow this guide to migrate your existing GitLab CI data to GitLab CE/EE.
-- [Monitoring uptime](user/admin_area/monitoring/health_check.md) Check the server status using the health check endpoint.
-- [Operations](administration/operations.md) Keeping GitLab up and running.
-- [Polling](administration/polling.md) Configure how often the GitLab UI polls for updates
-- [Raketasks](raketasks/README.md) Backups, maintenance, automatic webhook setup and the importing of projects.
-- [Reply by email](administration/reply_by_email.md) Allow users to comment on issues and merge requests by replying to notification emails.
-- [Repository checks](administration/repository_checks.md) Periodic Git repository checks.
-- [Repository storage paths](administration/repository_storage_paths.md) Manage the paths used to store repositories.
-- [Request Profiling](administration/monitoring/performance/request_profiling.md) Get a detailed profile on slow requests.
-- [Restart GitLab](administration/restart_gitlab.md) Learn how to restart GitLab and its components.
-- [Security](security/README.md) Learn what you can do to further secure your GitLab instance.
-- [Sidekiq Troubleshooting](administration/troubleshooting/sidekiq.md) Debug when Sidekiq appears hung and is not processing jobs.
-- [System hooks](system_hooks/system_hooks.md) Notifications when users, projects and keys are changed.
-- [Update](update/README.md) Update guides to upgrade your installation.
-- [User cohorts](user/admin_area/user_cohorts.md) View user activity over time.
-- [Web terminals](administration/integration/terminal.md) Provide terminal access to environments from within GitLab.
-- [Welcome message](customization/welcome_message.md) Add a custom welcome message to the sign-in page.
-- [Downgrade back to CE](downgrade_ee_to_ce/README.md) Follow this guide if you need to downgrade from EE to CE.
-- [Elasticsearch](integration/elasticsearch.md) Enable Elasticsearch.
-- [GitLab GEO](gitlab-geo/README.md) Configure GitLab GEO, a secondary read-only GitLab instance.
-- [Repository restrictions](user/admin_area/settings/account_and_limit_settings.md#repository-size-limit) Define size restrictions for your repositories to limit the space they occupy in your storage device. Includes LFS objects.
-- [Auditor users](administration/auditor_users.md) Create auditor users, with read-only access to the entire system.
-- [Database load balancing](administration/database_load_balancing.md) Distribute database queries amongst multiple database servers.
-- [User cohorts](user/admin_area/user_cohorts.md) View user activity over time.
+
+### User permissions
+
+- [Access restrictions](user/admin_area/settings/visibility_and_access_controls.md#enabled-git-access-protocols): Define which Git access protocols can be used to talk to GitLab
+- [Authentication/Authorization](topics/authentication/index.md#gitlab-administrators): Enforce 2FA, configure external authentication with LDAP, SAML, CAS and additional Omniauth providers.
+  - **(EES/EEP)** [Sync LDAP](administration/auth/ldap-ee.md)
+  - **(EES/EEP)** [Kerberos authentication](integration/kerberos.md)
+
+### GitLab admins' superpowers
+
+- [Container Registry](administration/container_registry.md): Configure Container Registry with GitLab.
+- [Custom Git hooks](administration/custom_hooks.md): Custom Git hooks (on the filesystem) for when webhooks aren't enough.
+- [Git LFS configuration](workflow/lfs/lfs_administration.md): Enable/disable Git LFS, change the location of LFS object storage.
+- [GitLab Pages configuration](administration/pages/index.md): Configure GitLab Pages.
+- [High Availability](administration/high_availability/README.md): Configure multiple servers for scaling or high availability.
+- [User cohorts](user/admin_area/user_cohorts.md): View user activity over time.
+- [Web terminals](administration/integration/terminal.md): Provide terminal access to environments from within GitLab.
+- **(EES/EEP)** [Audit logs and events](administration/audit_events.md): View the changes made within the GitLab server.
+- **(EES/EEP)** [Elasticsearch](integration/elasticsearch.md): A flexible, scalable and powerful search service to keep GitLab's search fast when dealing with huge amount of data.
+- **(EES/EEP)** [Email users](tools/email.md): Email GitLab users from within GitLab.
+- **(EES/EEP)** [Limit project size](user/admin_area/settings/account_and_limit_settings.md): Set a hard limit for your repositories' size.
+- **(EEP)** [Auditor users](administration/auditor_users.md): Users with read-only access to all projects, groups, and other resources on the GitLab instance.
+- **(EEP)** [GitLab GEO](gitlab-geo/README.md): Replicate your GitLab instance to other geographical locations as a read-only fully operational version.
+- **(EEP)** [Pivotal Tile](https://about.gitlab.com/2015/11/03/pivotal-cloud-foundry-tile-for-gitlab-ee/): Deploy GitLab as a pre-configured appliance using Ops Manager (BOSH) for Pivotal Cloud Foundry. See also: [Pivotal documentation](https://docs.pivotal.io/partners/gitlab/index.html).
+- **(EES/EEP)** [Database load balancing](administration/database_load_balancing.md): Distribute database queries among multiple database servers.
+- **(EES/EEP)** [Omnibus support for external MySQL DB](https://docs.gitlab.com/omnibus/settings/database.html#using-a-mysql-database-management-server-enterprise-edition-only): Omnibus package supports configuring an external MySQL database.
+- **(EES/EEP)** [Omnibus support for log forwarding](https://docs.gitlab.com/omnibus/settings/logs.html#udp-log-shipping-gitlab-enterprise-edition-only)
+- GitLab CI
+    - [CI admin settings](user/admin_area/settings/continuous_integration.md): Define max artifacts size and expiration.
+
+### Integrations
+
+- [Integrations](integration/README.md): How to integrate with systems such as JIRA, Redmine, Twitter.
+- [Koding](administration/integration/koding.md): Set up Koding to use with GitLab.
+- [Mattermost](user/project/integrations/mattermost.md): Set up GitLab with Mattermost.
+- **(EES/EEP)** [Jenkins](integration/jenkins.md): Set up GitLab with Jenkins.
+
+### Monitoring
+
+- [GitLab performance monitoring with InfluxDB](administration/monitoring/performance/introduction.md): Configure GitLab and InfluxDB for measuring performance metrics.
+- [GitLab performance monitoring with Prometheus](administration/monitoring/prometheus/index.md): Configure GitLab and Prometheus for measuring performance metrics.
+- [Monitoring uptime](user/admin_area/monitoring/health_check.md): Check the server status using the health check endpoint.
+
+### Performance
+
+- [Housekeeping](administration/housekeeping.md): Keep your Git repository tidy and fast.
+- [Operations](administration/operations.md): Keeping GitLab up and running.
+- [Polling](administration/polling.md): Configure how often the GitLab UI polls for updates
+- [Request Profiling](administration/monitoring/performance/request_profiling.md): Get a detailed profile on slow requests.
+
+### Customization
+
+- [Adjust your instance's timezone](workflow/timezone.md): Customize the default time zone of GitLab.
+- [Environment variables](administration/environment_variables.md): Supported environment variables that can be used to override their defaults values in order to configure GitLab.
+- [Header logo](customization/branded_page_and_email_header.md): Change the logo on the overall page and email header.
+- [Issue closing pattern](administration/issue_closing_pattern.md): Customize how to close an issue from commit messages.
+- [Libravatar](customization/libravatar.md): Use Libravatar instead of Gravatar for user avatars.
+- [Welcome message](customization/welcome_message.md): Add a custom welcome message to the sign-in page.
+
+### Admin tools
+
+- [Raketasks](raketasks/README.md): Backups, maintenance, automatic webhook setup and the importing of projects.
+    - [Backup and restore](raketasks/backup_restore.md): Backup and restore your GitLab instance.
+- [Reply by email](administration/reply_by_email.md): Allow users to comment on issues and merge requests by replying to notification emails.
+- [Repository checks](administration/repository_checks.md): Periodic Git repository checks.
+- [Repository storage paths](administration/repository_storage_paths.md): Manage the paths used to store repositories.
+- [Security](security/README.md): Learn what you can do to further secure your GitLab instance.
+- [System hooks](system_hooks/system_hooks.md): Notifications when users, projects and keys are changed.
+
+### Troubleshooting
+
+- [Debugging tips](administration/troubleshooting/debug.md): Tips to debug problems when things go wrong
+- [Log system](administration/logs.md): Where to look for logs.
+- [Sidekiq Troubleshooting](administration/troubleshooting/sidekiq.md): Debug when Sidekiq appears hung and is not processing jobs.
 
 ## Contributor documentation
 
-- [Development](development/README.md) All styleguides and explanations how to contribute.
-- [Legal](legal/README.md) Contributor license agreements.
+- [Development](development/README.md): All styleguides and explanations how to contribute.
+- [Legal](legal/README.md): Contributor license agreements.
+- [Writing documentation](development/writing_documentation.md): Contributing to GitLab Docs.

doc/migrate_ci_to_ce/README.md

-## Migrate GitLab CI to GitLab CE or EE
+# Migrate GitLab CI to GitLab CE or EE
 
 Beginning with version 8.0 of GitLab Community Edition (CE) and Enterprise
 Edition (EE), GitLab CI is no longer its own application, but is instead built
@@ -12,7 +12,7 @@ is not possible.**
 We recommend that you read through the entire migration process in this
 document before beginning.
 
-### Overview
+## Overview
 
 In this document we assume you have a GitLab server and a GitLab CI server. It
 does not matter if these are the same machine.
@@ -26,7 +26,7 @@ can be online for most of the procedure; the only GitLab downtime (if any) is
 during the upgrade to 8.0. Your CI service will be offline from the moment you
 upgrade to 8.0 until you finish the migration procedure.
 
-### Before upgrading
+## Before upgrading
 
 If you have GitLab CI installed using omnibus-gitlab packages but **you don't want to migrate your existing data**:
 
@@ -38,12 +38,12 @@ run `sudo gitlab-ctl reconfigure` and you can reach CI at `gitlab.example.com/ci
 
 If you want to migrate your existing data, continue reading.
 
-#### 0. Updating Omnibus from versions prior to 7.13
+### 0. Updating Omnibus from versions prior to 7.13
 
 If you are updating from older versions you should first update to 7.14 and then to 8.0.
 Otherwise it's pretty likely that you will encounter problems described in the [Troubleshooting](#troubleshooting).
 
-#### 1. Verify that backups work
+### 1. Verify that backups work
 
 Make sure that the backup script on both servers can connect to the database.
 
@@ -73,7 +73,7 @@ sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production SKIP=r
 If this fails you need to fix it before upgrading to 8.0. Also see
 https://about.gitlab.com/getting-help/
 
-#### 2. Check source and target database types
+### 2. Check source and target database types
 
 Check what databases you use on your GitLab server and your CI server.
   Look for the 'adapter:' line. If your CI server and your GitLab server use
@@ -102,7 +102,7 @@ cd /home/git/gitlab
 sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production
 ```
 
-#### 3. Storage planning
+### 3. Storage planning
 
 Decide where to store CI build traces on GitLab server. GitLab CI uses
   files on disk to store CI build traces. The default path for these build
@@ -111,34 +111,34 @@ traces is `/var/opt/gitlab/gitlab-ci/builds` (Omnibus) or
 a special location, or if you are using NFS, you should make sure that you
 store build traces on the same storage as your Git repositories.
 
-### I. Upgrading
+## I. Upgrading
 
 From this point on, GitLab CI will be unavailable for your end users.
 
-#### 1. Upgrade GitLab to 8.0
+### 1. Upgrade GitLab to 8.0
 
 First upgrade your GitLab server to version 8.0:
 https://about.gitlab.com/update/
 
-#### 2. Disable CI on the GitLab server during the migration
+### 2. Disable CI on the GitLab server during the migration
 
 After you update, go to the admin panel and temporarily disable CI.  As
   an administrator, go to **Admin Area** -> **Settings**, and under
 **Continuous Integration** uncheck **Disable to prevent CI usage until rake
 ci:migrate is run (8.0 only)**.
 
-#### 3. CI settings are now in GitLab
+### 3. CI settings are now in GitLab
 
 If you want to use custom CI settings (e.g. change where builds are
   stored), please update `/etc/gitlab/gitlab.rb` (Omnibus) or
 `/home/git/gitlab/config/gitlab.yml` (Source).
 
-#### 4. Upgrade GitLab CI to 8.0
+### 4. Upgrade GitLab CI to 8.0
 
 Now upgrade GitLab CI to version 8.0. If you are using Omnibus packages,
   this may have already happened when you upgraded GitLab to 8.0.
 
-#### 5. Disable GitLab CI on the CI server
+### 5. Disable GitLab CI on the CI server
 
 Disable GitLab CI after upgrading to 8.0.
 
@@ -154,9 +154,9 @@ cd /home/gitlab_ci/gitlab-ci
 sudo -u gitlab_ci -H bundle exec whenever --clear-crontab RAILS_ENV=production
 ```
 
-### II. Moving data
+## II. Moving data
 
-#### 1. Database encryption key
+### 1. Database encryption key
 
 Move the database encryption key from your CI server to your GitLab
   server. The command below will show you what you need to copy-paste to your
@@ -174,7 +174,7 @@ cd /home/gitlab_ci/gitlab-ci
 sudo -u gitlab_ci -H bundle exec rake backup:show_secrets RAILS_ENV=production
 ```
 
-#### 2. SQL data and build traces
+### 2. SQL data and build traces
 
 Create your final CI data export. If you are converting from MySQL to
   PostgreSQL, add ` MYSQL_TO_POSTGRESQL=1` to the end of the rake command. When
@@ -192,7 +192,7 @@ cd /home/gitlab_ci/gitlab-ci
 sudo -u gitlab_ci -H bundle exec rake backup:create RAILS_ENV=production
 ```
 
-#### 3. Copy data to the GitLab server
+### 3. Copy data to the GitLab server
 
 If you were running GitLab and GitLab CI on the same server you can skip this
 step.
@@ -209,7 +209,7 @@ ssh -A ci_admin@ci_server.example
 scp /path/to/12345_gitlab_ci_backup.tar gitlab_admin@gitlab_server.example:~
 ```
 
-#### 4. Move data to the GitLab backups folder
+### 4. Move data to the GitLab backups folder
 
 Make the CI data archive discoverable for GitLab. We assume below that you
 store backups in the default path, adjust the command if necessary.
@@ -223,7 +223,7 @@ sudo mv /path/to/12345_gitlab_ci_backup.tar /var/opt/gitlab/backups/
 sudo mv /path/to/12345_gitlab_ci_backup.tar /home/git/gitlab/tmp/backups/
 ```
 
-#### 5. Import the CI data into GitLab.
+### 5. Import the CI data into GitLab.
 
 This step will delete any existing CI data on your GitLab server. There should
 be no CI data yet because you turned CI on the GitLab server off earlier.
@@ -239,7 +239,7 @@ cd /home/git/gitlab
 sudo -u git -H bundle exec rake ci:migrate RAILS_ENV=production
 ```
 
-#### 6. Restart GitLab
+### 6. Restart GitLab
 
 ```
 # On your GitLab server:
@@ -251,7 +251,7 @@ sudo gitlab-ctl restart sidekiq
 sudo service gitlab reload
 ```
 
-### III. Redirecting traffic
+## III. Redirecting traffic
 
 If you were running GitLab CI with Omnibus packages and you were using the
 internal NGINX configuration your CI service should now be available both at
@@ -261,7 +261,7 @@ If you installed GitLab CI from source we now need to configure a redirect in
 NGINX so that existing CI runners can keep using the old CI server address, and
 so that existing links to your CI server keep working.
 
-#### 1. Update Nginx configuration
+### 1. Update Nginx configuration
 
 To ensure that your existing CI runners are able to communicate with the
 migrated installation, and that existing build triggers still work, you'll need
@@ -317,22 +317,22 @@ You should also make sure that you can:
 1. `curl https://YOUR_GITLAB_SERVER_FQDN/` from your previous GitLab CI server.
 1. `curl https://YOUR_CI_SERVER_FQDN/` from your GitLab CE (or EE) server.
 
-#### 2. Check Nginx configuration
+### 2. Check Nginx configuration
 
     sudo nginx -t
 
-#### 3. Restart Nginx
+### 3. Restart Nginx
 
     sudo /etc/init.d/nginx restart
 
-#### Restore from backup
+### Restore from backup
 
 If something went wrong and you need to restore a backup, consult the [Backup
 restoration](../raketasks/backup_restore.md) guide.
 
-### Troubleshooting
+## Troubleshooting
 
-#### show:secrets problem (Omnibus-only)
+### show:secrets problem (Omnibus-only)
 If you see errors like this:
 ```
 Missing `secret_key_base` or `db_key_base` for 'production' environment. The secrets will be generated and stored in `config/secrets.yml`
@@ -343,7 +343,7 @@ Errno::EACCES: Permission denied @ rb_sysopen - config/secrets.yml
 This can happen if you are updating from versions prior to 7.13 straight to 8.0.
 The fix for this is to update to Omnibus 7.14 first and then update it to 8.0.
 
-#### Permission denied when accessing /var/opt/gitlab/gitlab-ci/builds
+### Permission denied when accessing /var/opt/gitlab/gitlab-ci/builds
 To fix that issue you have to change builds/ folder permission before doing final backup:
 ```
 sudo chown -R gitlab-ci:gitlab-ci /var/opt/gitlab/gitlab-ci/builds
@@ -354,7 +354,7 @@ Then before executing `ci:migrate` you need to fix builds folder permission:
 sudo chown git:git /var/opt/gitlab/gitlab-ci/builds
 ```
 
-#### Problems when importing CI database to GitLab
+### Problems when importing CI database to GitLab
 If you were migrating CI database from MySQL to PostgreSQL manually you can see errors during import about missing sequences:
 ```
 ALTER SEQUENCE

doc/topics/git/index.md

@@ -17,6 +17,10 @@ We've gathered some resources to help you to get the best from Git with GitLab.
 - [Start using Git on the command line](../../gitlab-basics/start-using-git.md)
 - [Command Line basic commands](../../gitlab-basics/command-line-commands.md)
 - [GitLab Git Cheat Sheet (download)](https://gitlab.com/gitlab-com/marketing/raw/master/design/print/git-cheatsheet/print-pdf/git-cheatsheet.pdf)
+- Commits
+  - [Revert a commit](../../user/project/merge_requests/revert_changes.md#reverting-a-commit) 
+  - [Cherry-picking a commit](../../user/project/merge_requests/cherry_pick_changes.md#cherry-picking-a-commit)
+  - [Squashing commits](../../workflow/gitlab_flow.md#squashing-commits-with-rebase)
 - **Articles:**
   - [Git Tips & Tricks](https://about.gitlab.com/2016/12/08/git-tips-and-tricks/)
   - [Eight Tips to help you work better with Git](https://about.gitlab.com/2015/02/19/8-tips-to-help-you-work-better-with-git/)
@@ -50,7 +54,7 @@ We've gathered some resources to help you to get the best from Git with GitLab.
 ## Git LFS
 
 - [Git LFS](../../workflow/lfs/manage_large_binaries_with_git_lfs.md)
-- [Git-Annex to Git-LFS migration guide](https://docs.gitlab.com/ee/workflow/lfs/migrate_from_git_annex_to_git_lfs.html)
+- [Git-Annex to Git-LFS migration guide](../../workflow/lfs/migrate_from_git_annex_to_git_lfs.md)
 - **Articles:**
   - [Getting Started with Git LFS](https://about.gitlab.com/2017/01/30/getting-started-with-git-lfs-tutorial/)
   - [Towards a production quality open source Git LFS server](https://about.gitlab.com/2015/08/13/towards-a-production-quality-open-source-git-lfs-server/)