Doc: Search through GitLab

11 files changed, 117 insertions, 23 deletions

diff --git a/doc/README.md b/doc/README.md
index df11d5e49a8..b0b3d2156a7 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -18,62 +18,62 @@ All technical content published by GitLab lives in the documentation, including:
 - [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.
-- [GitLab as OAuth2 authentication service provider](integration/oauth_provider.md). It allows you to login to other applications from GitLab.
 - [Container Registry](user/project/container_registry.md) Learn how to use GitLab Container Registry.
+- [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.
-- [Importing to GitLab](workflow/importing/README.md) Import your projects from GitHub, Bitbucket, GitLab.com, FogBugz and SVN into GitLab.
 - [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.
+- [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.
-- [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.
 
 ## Administrator documentation
 
 - [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.
+- [Authentication/Authorization](administration/auth/README.md) Configure external authentication with LDAP, SAML, CAS and additional Omniauth providers.
+- [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.
-- [Restart GitLab](administration/restart_gitlab.md) Learn how to restart GitLab and its components.
 - [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.
-- [Web terminals](administration/integration/terminal.md) Provide terminal access to environments from within GitLab.
 - [Libravatar](customization/libravatar.md) Use Libravatar instead of Gravatar for user avatars.
 - [Log system](administration/logs.md) Log system.
-- [Environment Variables](administration/environment_variables.md) to configure GitLab.
+- [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.
 - [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.
+- [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.
-- [Header logo](customization/branded_page_and_email_header.md) Change the logo on the overall page and email header.
-- [Reply by email](administration/reply_by_email.md) Allow users to comment on issues and merge requests by replying to notification emails.
-- [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.
-- [Git LFS configuration](workflow/lfs/lfs_administration.md)
-- [Housekeeping](administration/housekeeping.md) Keep your Git repository tidy and fast.
-- [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.
-- [Request Profiling](administration/monitoring/performance/request_profiling.md) Get a detailed profile on slow requests.
-- [Monitoring uptime](user/admin_area/monitoring/health_check.md) Check the server status using the health check endpoint.
-- [Debugging Tips](administration/troubleshooting/debug.md) Tips to debug problems when things go wrong
-- [Sidekiq Troubleshooting](administration/troubleshooting/sidekiq.md) Debug when Sidekiq appears hung and is not processing jobs.
-- [High Availability](administration/high_availability/README.md) Configure multiple servers for scaling or high availability.
-- [Container Registry](administration/container_registry.md) Configure Docker Registry with GitLab.
 
 ## Contributor documentation
 
diff --git a/doc/user/search/img/filter_issues_project.gif b/doc/user/search/img/filter_issues_project.gif
new file mode 100644
index 00000000000..d547588be5d
--- /dev/null
+++ b/doc/user/search/img/filter_issues_project.gif
diff --git a/doc/user/search/img/issues_any_assignee.png b/doc/user/search/img/issues_any_assignee.png
new file mode 100755
index 00000000000..2f902bcc66c
--- /dev/null
+++ b/doc/user/search/img/issues_any_assignee.png
diff --git a/doc/user/search/img/issues_assigned_to_you.png b/doc/user/search/img/issues_assigned_to_you.png
new file mode 100755
index 00000000000..36c670eedd5
--- /dev/null
+++ b/doc/user/search/img/issues_assigned_to_you.png
diff --git a/doc/user/search/img/issues_author.png b/doc/user/search/img/issues_author.png
new file mode 100755
index 00000000000..792f9746db6
--- /dev/null
+++ b/doc/user/search/img/issues_author.png
diff --git a/doc/user/search/img/issues_mrs_shortcut.png b/doc/user/search/img/issues_mrs_shortcut.png
new file mode 100755
index 00000000000..6380b337b54
--- /dev/null
+++ b/doc/user/search/img/issues_mrs_shortcut.png
diff --git a/doc/user/search/img/left_menu_bar.png b/doc/user/search/img/left_menu_bar.png
new file mode 100755
index 00000000000..d68a71cba8e
--- /dev/null
+++ b/doc/user/search/img/left_menu_bar.png
diff --git a/doc/user/search/img/project_search.png b/doc/user/search/img/project_search.png
new file mode 100755
index 00000000000..3150b40de29
--- /dev/null
+++ b/doc/user/search/img/project_search.png
diff --git a/doc/user/search/img/search_issues_board.png b/doc/user/search/img/search_issues_board.png
new file mode 100755
index 00000000000..84048ae6a02
--- /dev/null
+++ b/doc/user/search/img/search_issues_board.png
diff --git a/doc/user/search/img/sort_projects.png b/doc/user/search/img/sort_projects.png
new file mode 100755
index 00000000000..9bf2770b299
--- /dev/null
+++ b/doc/user/search/img/sort_projects.png
diff --git a/doc/user/search/index.md b/doc/user/search/index.md
new file mode 100644
index 00000000000..9d1ca1adcb2
--- /dev/null
+++ b/doc/user/search/index.md
@@ -0,0 +1,94 @@
+# Search through GitLab
+
+## Issues and merge requests
+
+To search through issues and merge requests in multiple projects, you can use the left-sidebar.
+
+Click the menu bar, then **Issues** or **Merge Requests**, which work in the same way,
+therefore, the following notes are valid for both.
+
+The number displayed on their right represents the number of issues and merge requests assigned to you.
+
+![menu bar - issues and MRs assigned to you](img/left_menu_bar.png)
+
+When you click **Issues**, you'll see the opened issues assigned to you straight away:
+
+![Issues assigned to you](img/issues_assigned_to_you.png)
+
+You can filter them by **Author**, **Assignee**, **Milestone**, and **Labels**,
+searching through **Open**, **Closed**, and **All** issues.
+
+Of course, you can combine all filters together.
+
+### Issues and MRs assigned to you or created by you
+
+You'll find a shortcut to issues and merge requests create by you or assigned to you
+on the search field on the top-right of your screen:
+
+![shortcut to your issues and mrs](img/issues_mrs_shortcut.png)
+
+## Issues and merge requests per project
+
+If you want to search for issues present in a specific project, navigate to
+a project's **Issues** tab, and click on the field **Search or filter results...**. It will
+display a dropdown menu, from which you can add filters per author, assignee, milestone, label,
+and weight. When done, press **Enter** on your keyboard to filter the issues.
+
+![filter issues in a project](img/filter_issues_project.gif)
+
+The same process is valid for merge requests. Navigate to your project's **Merge Requests** tab,
+and click **Search or filter results...**. Merge requests can be filtered by author, assignee,
+milestone, and label.
+
+### Shortcut
+
+You'll also find a shortcut on the search field on the top-right of the project's dashboard to
+quickly access issues and merge requests created or assigned to you within that project:
+
+![search per project - shortcut](img/project_search.png)
+
+## Todos
+
+Your [todos](../../workflow/todos.md#gitlab-todos) can be searched by "to do" and "done".
+You can [filter](../../workflow/todos.md#filtering-your-todos) them per project,
+author, type, and action. Also, you can sort them by
+[**Label priority**](../../user/project/labels.md#prioritize-labels),
+**Last created** and **Oldest created**.
+
+## Projects
+
+You can search through your projects from the left menu, by clicking the menu bar, then **Projects**.
+On the field **Filter by name**, type the project or group name you want to find, and GitLab
+will filter them for you as you type.
+
+You can also look for the projects you starred (**Starred projects**), and **Explore** all
+public and internal projects available in GitLab.com, from which you can filter by visibitily,
+through **Trending**, best rated with **Most starts**, or **All** of them.
+
+You can also sort them by **Name**, **Last created**, **Oldest created**, **Last updated**,
+**Oldest updated**, **Owner**, and choose to hide or show **archived projects**:
+
+![sort projects](img/sort_projects.png)
+
+## Groups
+
+Similarly to [projects search](#projects), you can search through your groups from
+the left menu, by clicking the menu bar, then **Groups**.
+
+On the field **Filter by name**, type the group name you want to find, and GitLab
+will filter them for you as you type.
+
+You can also **Explore** all public and internal groups available in GitLab.com,
+and sort them by **Last created**, **Oldest created**, **Last updated**, or **Oldest updated**.
+
+## Issue Boards
+
+From an [Issue Board](../../user/project/issue_board.md), you can filter issues by **Author**, **Assignee**, **Milestone**, and **Labels**.
+You can also filter them by name (issue title), from the field **Filter by name**, which is loaded as you type.
+
+When you want to search for issues to add to lists present in your Issue Board, click
+the button **Add issues** on the top-right of your screen, opening a modal window from which
+you'll be able to, besides filtering them by **Name**, **Author**, **Assignee**, **Milestone**,
+and **Labels**, select multiple issues to add to a list of your choice:
+
+![search and select issues to add to board](img/search_issues_board.png)