Add documentation on why to disable Core Search

We should definitely not change a completely unrelated module's configuration on our own, so the second option is out of the question.
Displaying a warning might make sense, yes – it might just be annoying to people who know what they're doing and still want that. But as long as it's just a warning, not an error, I guess it would be acceptable. (If it annoys too many, we could add a state to say "yes, I'm sure, I want both".

OK, I'm starting to work on this.

@ marcvangend: Great! In this case, please set the "Assigned" field to yourself.

This patch adds a warning:
1) During installation of the Search API module
2) On the Status Report page

See screenshots.

Thanks for providing the patch!

+++ b/search_api.install
@@ -90,3 +90,45 @@ function search_api_schema() {
+    return t('The default Drupal Search module is still enabled. If you are using Search API, you probably want to <a href="/admin/modules/uninstall">uninstall</a> the Search module for performance reasons.');

This is not the correct way to include a link in translated text, since this changes the base string if the path changes, and also doesn't use the correct Drupal way to create the link (breaking, e.g., when Drupal is installed in a sub-directory).
I now corrected the line to:

return t('The default Drupal Search module is still enabled. If you are using Search API, you probably want to <a href="@url">uninstall</a> the Search module for performance reasons.', array('@url' => \Drupal::url('system.modules_uninstall')));

Other than that, the patch looks fine, thanks again!
Committed.

Ah, sorry, Nick, committed before seeing your comment. Makes sense, though, setting back to "Active" – we should add that information in the handbook and then link to it in the message.

Just a bit of clean-up and replaced deprecated

add that information in the handbook

Which page exactly?

proper one

Which page exactly?

Maybe just as another question in the FAQs? Or as a new child page of the "Getting started" section.

Do you still need a hand with this or is it sorted now?

The patch seems to need a re-roll and we'd still need someone to add this to the documentation, if you're up for it.

+++ b/search_api.install
@@ -107,8 +108,8 @@ function search_api_install() {
     $message = _search_api_search_module_warning();
     if ($message) {

@@ -158,7 +158,9 @@ function search_api_requirements($phase) {
 function _search_api_search_module_warning() {

if this is a only usage of the function better move the check with inline code

@andypost
it is used twice
in search_api_install() and in search_api_requirements()

Filed follow-up #2670666: Get rid of search_api_install() message

I'd better removed this hook install and added hook_help() mention about that after configuring module you can disable core search in favor of the module

RTBC+1

updated patch

+++ b/search_api.module
@@ -15,9 +16,16 @@ use Drupal\search_api\Plugin\search_api\datasource\ContentEntity;
 function search_api_help($route_name) {
+  // Could be cached until module un/install.
   switch ($route_name) {
     case 'search_api.overview':
-      return t('Below is a list of indexes grouped by the server they are associated with. A server is the definition of the actual indexing, querying and storage engine (e.g., an Apache Solr server, the database, …). An index defines the indexed content (e.g., all content and all comments on "Article" posts).');
+      $message = '<p>' . t('Below is a list of indexes grouped by the server they are associated with. A server is the definition of the actual indexing, querying and storage engine (e.g., an Apache Solr server, the database, …). An index defines the indexed content (e.g., all content and all comments on "Article" posts).') . '</p>';
+      if (Drupal::moduleHandler()->moduleExists('search')) {

great! but please put //comment inside if() with message

thnx @andypost , patch updated

great, let's get maintainer's opinion

See #2670666-7: Get rid of search_api_install() message: if we want to keep the other issue, I would say this is completely off-topic for this one. Here, we should add documentation on the reasons for disabling Core Search to the handbook, and then add a link to that to the help message (and a link to the "Uninstall" page, of course).
We can also do all that just in this issue, since it's more or less just a follow-up to what was committed. But then there would be no point in having the other issue. Or, last option, mark this issue as fixed and change the other issue to a general follow-up issue.
Now, it's completely unclear what either of them should implement.

I'd better refocus this issue to update help page and other one to clean-up useless hook_install()

Looks that's exactly the same as was commited in #2670666: Get rid of search_api_install() message

Yeah, so here we just have to add the documentation to the handbook and link to that.

Information about Search API and Drupal Search modules has been added to Getting started chapter in handbook. Link to this page has been added to message.

Link looks good.

Actually - that link goes to a drupal 7 page of documentation, is there a better place we can link to? The issue is on the page there - but I think this is a good reason to start / improve drupal 8 docs.

Back to NW for that.

Checked Drupal 7 Search module - there is the same problem too. So this information is valid for Drupal 7 and 8 both.

In that case, we can keep the link as-is.

I don't think "Getting started" is the best place for this, and the information was also a bit sparse.
Moved and expanded the documentation in the handbook and updated the patch.

Thanks for reviewing! Committed.
Thanks again, everyone!