Problem/Motivation

#3041924: [META] Convert hook_help() module overview text to topics for the search module(s).

Proposed resolution

Take the information that is currently in the hook_help module overview section for the module(s), and make sure the information is in one or more Twig help topic files. Steps:

  1. Find the hook_help() implementation function in the core/modules/MODULENAME/MODULENAME.module file(s). For example, for the core Contact module, the module files is core/modules/contact/contact.module, and the function is called contact_help().
  2. Locate the module overview portion of this function. This is located just after some lines that look something like this:
      switch ($route_name) {
        case 'help.page.contact':
    

    And ends either at the end of the function, or where you find another case 'something': line.

  3. We want to end up with one or more topics about the tasks that you can do with this module, and possibly a section header topic. So, read the help and figure out a good way to logically divide it up into tasks and sections. See Standards for Help Topics for information on how to do this.
  4. See if some of these tasks are already documented in existing topics. Currently, all topics are in core/modules/help_topics/help_topics. Note that to see existing topics, you will need to enable the experimental Help Topics module (available in the latest dev versions of Drupal 8.x).
  5. For each task or section topic that needs to be written, make a new Twig topic file (see Standards for Help Topics) in core/modules/help_topics/help_topics. You will need to choose the appropriate module prefix for the file name -- the module that is required for the functionality. Alternatively, if the information spans several modules or if the information should be visible before the module is installed, you can use the "core" file name prefix. For instance, it might be useful to know that to get a certain functionality, you need to turn on a certain module (so that would be in the core prefix), but then the details of how to use it should only be visible once that module is turned on (so that would be in the module prefix).
  6. File names must be MODULENAME.TOPICNAME.html.twig -- for example, in the Action module, you could create a topic about managing actions with filename action.managing.html.twig (and "MODULENAME" can be "core" as discussed above).
  7. Make a patch file that adds/updates the Twig templates. The patch should not remove the text from the hook_help() implementation (that will be done separately).

Remaining tasks

a) Make a patch (see Proposed Resolution section).

b) Review the patch:

  1. Apply the patch.
  2. Turn on the experimental Help Topics module in your site, as well as the module(s) listed in this issue.
  3. Visit the page for each topic that is created or modified in this patch. The topics are files in the patch ending in .html.twig. If you find a file, such as core/modules/help_topics/help_topics/action.configuring.html.twig, you can view the topic at the URL admin/help/topic/action.configuring within your site.
  4. Review the topic text that you can see on the page, making sure of the following aspects:
    • The text is written in clear, simple, straightforward language
    • No grammar/punctuation errors
    • Valid HTML -- you can use http://validator.w3.org/ to check
    • Links within the text work
    • Instructions for tasks work
    • Adheres to Standards for Help Topics [for some aspects, you will need to look at the Twig file rather than the topic page].
  5. Read the old "module overview" topic(s) for the module(s), at admin/help/MODULENAME. Verify that all the tasks described in these overview pages are covered in the topics you reviewed.

User interface changes

Help topics will be added to cover tasks currently covered in modules' hook_help() implementations.

API changes

None.

Data model changes

None.

Release notes snippet

None.

CommentFileSizeAuthor
#82 3047719-82.patch10.52 KBbatigolix
#79 interdiff_79.txt4.89 KBManav
#79 3047719-79.patch10.52 KBManav
#78 interdiff_77.txt4.89 KBManav
#78 3047719-77.patch10.51 KBManav
#74 interdiff.txt6.89 KBjhodgdon
#74 3047719-74.patch10.51 KBjhodgdon
#62 3047719-62.patch10.17 KBjhodgdon
#52 interdiff_48-52.txt1.02 KBhash6
#52 3047719-52.patch10.4 KBhash6
#48 interdiff_46-48.txt12.45 KBagrochal
#48 3047719-48.patch10.54 KBagrochal
#46 interdiff_44-46.txt12.55 KBagrochal
#46 3047719-46.patch9.39 KBagrochal
#44 interdiff_39-44.txt8.62 KBagrochal
#44 3047719-44.patch7.85 KBagrochal
#40 Screenshot from 2020-01-08 12-41-42.png122.97 KBshimpy
#40 Screenshot from 2020-01-08 12-41-31.png87.79 KBshimpy
#40 Screenshot from 2020-01-08 12-41-19.png110.16 KBshimpy
#40 Screenshot from 2020-01-08 12-41-08.png147.9 KBshimpy
#39 interdiff.txt12.59 KBshimpy
#39 3047719_39.patch7.73 KBshimpy
#33 interdiff_31-33.txt13.05 KBagrochal
#33 3047719-33.patch9.67 KBagrochal
#31 3047719-31.patch10.9 KBagrochal
#29 3047719-29.patch10.85 KBagrochal
#21 help_topic_search.patch11.34 KBshimpy
#20 Screen Shot 2019-09-20 at 12.07.09 PM.png255.5 KBalonaoneill
#20 Screen Shot 2019-09-20 at 12.00.39 PM.png378.42 KBalonaoneill
#20 Screen Shot 2019-09-20 at 11.57.27 AM.png204.83 KBalonaoneill
#20 Screen Shot 2019-09-20 at 11.54.51 AM.png223.18 KBalonaoneill
#20 Screen Shot 2019-09-20 at 11.51.34 AM.png192.03 KBalonaoneill
#17 help_topic_search.patch11.32 KBshimpy
#15 Screenshot at 2019-09-18 15-22-41.png86.95 KBshimpy
#15 Screenshot at 2019-09-18 15-22-57.png93.42 KBshimpy
#15 Screenshot at 2019-09-18 15-23-05.png90.02 KBshimpy
#15 Screenshot at 2019-09-18 15-23-13.png97.75 KBshimpy
#15 Screenshot at 2019-09-18 15-25-52.png123.72 KBshimpy
#15 Screenshot at 2019-09-18 15-26-04.png102.24 KBshimpy
#15 help_topic_search.patch11.39 KBshimpy
#9 Screen Shot 2019-07-30 at 11.19.39 AM.png70.73 KBalonaoneill
#9 Screen Shot 2019-07-30 at 11.17.02 AM.png133.69 KBalonaoneill
#9 Screen Shot 2019-07-30 at 11.16.03 AM.png70.73 KBalonaoneill
#9 Screen Shot 2019-07-30 at 11.15.07 AM.png51.26 KBalonaoneill
#9 Screen Shot 2019-07-30 at 11.14.34 AM.png64.16 KBalonaoneill
#9 Screen Shot 2019-07-30 at 11.06.06 AM.png42.46 KBalonaoneill
#9 Screen Shot 2019-07-30 at 11.22.53 AM.png41.46 KBalonaoneill
#4 3047719-search_module_help_topics.patch7.68 KB0Sarah0Al
Support from Acquia helps fund testing for Drupal Acquia logo

Comments

Sarahphp1 created an issue. See original summary.

0Sarah0Al’s picture

Title: Convert THISMODULE module hook_help() to topic(s) » Convert search module hook_help() to topic(s)
benjifisher’s picture

@Sarahphp1, thanks for creating the issue!

0Sarah0Al’s picture

Please check the patch, and let me know if it needs modification or re-writing or whatever.. :)

0Sarah0Al’s picture

Status: Postponed » Needs review
jhodgdon’s picture

Status: Needs review » Postponed

We need to postpone this until the #2920309: Add experimental module for Help Topics gets committed. No idea when/if that might happen right now...

jhodgdon’s picture

Status: Postponed » Needs review

That issue was committed, so we can un-postpone this now!

jhodgdon’s picture

Issue summary: View changes

Updating issue summary to latest template.

alonaoneill’s picture

1. Patch applied via STM
2. The experimental Help Topics module was enabled (Added screenshot below)
3. Reviewed each topic that was created and modified in this patch. Reviewed the patch for spelling and grammar. The topics are files in the patch ending in .html.twig. URLs work as well. (Added screenshot below with each topic)
4. Verified that all the tasks described in the overviews are covered in the topics.

jhodgdon’s picture

Issue summary: View changes

Updated issue summary with better instructions/guidelines

jhodgdon’s picture

Issue summary: View changes
Status: Needs review » Needs work

Another iteration on the instructions/guidelines.

Glancing at this patch, it doesn't meet our new and improved guidelines on topic titles and format. Please check the issue summary for new instructions.

jhodgdon’s picture

Issue summary: View changes

We've migrated the help topic standards to https://www.drupal.org/docs/develop/documenting-your-project/help-topic-... so updating issue summary again.

jhodgdon’s picture

Assigned: Unassigned » jhodgdon

I will make the next patch for this issue, over the next few days.

jhodgdon’s picture

Assigned: jhodgdon » Unassigned

I had less time than I thought I would.

shimpy’s picture

Hii @jhodgdon I have created a patch for the help_topic_search module as per the Standards for Help Topics. I have created a top level Search overview and all the other as related topics such as Displaying the search block , Extending the search module , configuring the search , managing search index and search module permissions.

Please review and let me know if you want further more changes. For reference I am adding the screenshots as well.

Gayathri J’s picture

Hii @Shimpy I applied your patch working fine each and every steps and goal was very clear.

shimpy’s picture

Re-created patch without end-line warnings. Please Review.

Gayathri J’s picture

Status: Needs review » Reviewed & tested by the community
Gayathri J’s picture

Status: Reviewed & tested by the community » Needs review
alonaoneill’s picture

I found a few typos and spaces missing. Screenshots added.

shimpy’s picture

Hii @alonaoneill Thanks for reviewing the patch and as per your suggestions I have recreated a patch with all the typos and space changes, Can u please review it again. Thanks

volkswagenchick’s picture

Issue tags: +badcamp2019

Tagging for badcamp2019, thanks! (October 2-5)

jhodgdon’s picture

Status: Needs review » Needs work

Thanks for the patches!

Please review the Help topic standards" and make a new patch.

I started to review, but the first thing I noticed is that the titles and Goal sections of the topics in the patch do not match the standards, so I stopped reviewing there.

Version: 8.8.x-dev » 8.9.x-dev

Drupal 8.8.0-alpha1 will be released the week of October 14th, 2019, which means new developments and disruptive changes should now be targeted against the 8.9.x-dev branch. (Any changes to 8.9.x will also be committed to 9.0.x in preparation for Drupal 9’s release, but some changes like significant feature additions will be deferred to 9.1.x.). For more information see the Drupal 8 and 9 minor version schedule and the Allowed changes during the Drupal 8 and 9 release cycles.

Gayathri J’s picture

jhodgdon’s picture

Issue summary: View changes

We just found out that all topic Twig files currently need to go into core/modules/help_topics/help_topics (with their finalized module-based file names), for the time being until the Help Topics module is stable. Updating issue summary. Patch will need to be updated too.

jhodgdon’s picture

Issue summary: View changes
agrochal’s picture

Assigned: shimpy » Unassigned

Working on that.

agrochal’s picture

Status: Needs work » Needs review
FileSize
10.85 KB

I've created a patch to add help topics. I've used the HTML validator.

Status: Needs review » Needs work

The last submitted patch, 29: 3047719-29.patch, failed testing. View results

agrochal’s picture

Status: Needs work » Needs review
FileSize
10.9 KB

Sorry, I missed trans tag. Here's fixed patch.

jhodgdon’s picture

Status: Needs review » Needs work

Thanks for the patch! This is looking pretty good. A few things to address:

a) in the block topic:
- "Displays the Search block." (goal) --> should be "Display".
- This topic has no steps. If it is a task topic, it should have steps. Probably the steps would be something like this:
1. Follow the steps in (insert link to the block placement topic here) to place the (insert the actual name of the block here) block.
2. When configuring the block, use the following settings: (add a DL list or table of the specific settings for the block).

b) In general, in task topics, put background information into "what is" headings. Don't just make a separate paragraph under Goal, which is what I am seeing in several of the topics. See https://www.drupal.org/docs/develop/documenting-your-project/help-topic-... for more information.

c) Don't say "this will take you to" in navigation. There is an example of how to do navigation in the help topic standards page. What we do is turn the last step of the navigation into a link, which is more concise.

d) Please verify that the "Additional resources" listed actually contain information that is not already in the topic, and which is useful. If there is crucial information on these pages, consider adding it to the topic; if not, consider removing the link.

e) I think I would prefer to see the "extending" topic just added as part of the overview topic, because we don't really want to give steps on how to enable modules in this topic (we should have just one topic about how to enable modules, which is part of a different issue).

agrochal’s picture

Status: Needs work » Needs review
FileSize
9.67 KB
13.05 KB

Thank you for that well described feedback :)
I followed your advice and created the new patch. I attach the interdiff as well.

Status: Needs review » Needs work

The last submitted patch, 33: 3047719-33.patch, failed testing. View results

agrochal’s picture

Status: Needs work » Needs review

There was something wrong with the tests, I've made retest and everything is okay.

jhodgdon’s picture

Thanks for the patch! I think it is looking pretty good, and we're down to small corrections:

a) configuring topic:
- "What are Search Pages?" section -- needs a rewrite for grammar/clarity. Also, I think the info about settings common to all search pages should come first, and the sentence saying some have additional settings should come last?
- Last step -- needs rewrite for grammar/clarity. Also only UI text should be in italics, not half the sentence? Also maybe should be divided into two or more steps, and give clear instructions, like "Click Add page" and "Enter the desired page title and URL" or whatever.

b) indexing topic:
- Title "Managing Search Index" should be "Managing the search index" -- actually all topics, like other UI text in Drupal, should only have the first word capitalized.
- "Search Index" is not a proper noun and does not need to be capitalized in the Goal section either, or in the "What is" heading (both of which also need a "the" in there).
- Don't talk about "this module". This is a task-oriented topic, not a module overview.

OK I have to run off, there might be more, but I only got through part of these topics... Thanks again!

jhodgdon’s picture

Status: Needs review » Needs work

Here's the rest of my review:

b) indexing topic (continued)
- This topic should not talk about how to configure a search page. It should link to the configuring page instead, if that is even necessary.
- I think the topic should talk about the indexing information at the top and bottom of the search admin page -- maybe one of the steps would be to look at that info (or two steps, as there are two areas) and explain how to understand the state of the index
- Don't put button/link text in quotes, like <em>clicking the "Re-index site" </em> button. This should just say Click <em>Re-index site</em> (do not use the word "button" either).

c) We don't want topics that need the word "module" in their titles. So "Using Search module" should just be probably "Overview of search" or "Searching your site" or something like that. We are trying to not have module overview topics. We want topics oriented towards tasks.

That topic also shouldn't have h2 headings called "What is search module" or "About" or "Extending". Please read the help topic guidelines page: https://www.drupal.org/docs/develop/documenting-your-project/help-topic-...

d) The permissions topic is not much of a task topic really... We have a topic about permissions in general that is in another issue. I think maybe we should just put information about the permissions into the overview topic and not have a task topic about setting the search permissions at all.

shimpy’s picture

Assigned: Unassigned » shimpy
shimpy’s picture

Status: Needs work » Needs review
FileSize
7.73 KB
12.59 KB

Hii I have created a patch based on the instructions in #36 and #37 . Also created a interdiff. Please review.

shimpy’s picture

agrochal’s picture

Assigned: shimpy » Unassigned
Status: Needs review » Needs work

Hey, I’ve just made a quick look and saw mistake in 4th step of configuring topic “search pages search pages”. Anyway, please check out the assignment guide. I’ve written comment that I am working on it and actually I’m at the end of corrections mentioned in #36 and #37. Also, this issue is the part of my participation in a contest Google Code-in, and I’ll be thankful if you let me finish it :)

shimpy’s picture

hii @agrochal before working on the issue . i was following this issue form start so I have get it assigned to myself, then only i created a patch for it. Anyhow you can continue working on it..

jhodgdon’s picture

It is a good practice to keep an issue assigned to you until you are done working on it. I see people all the time who upload a patch and then unassign the issue, but if you keep it assigned to yourself, it is an indication that if there is a Needs Work review, you plan to keep working on new patches. Anyway, it seems like you two have agreed on a way forward. Thanks for both of your help!

agrochal’s picture

Assigned: Unassigned » agrochal
Status: Needs work » Needs review
FileSize
7.85 KB
8.62 KB

Thanks @shimpy for understanding and @jhodgdon for that review.
I attach my patch, and interdiff with patch from #39.
I will assign this issue for myself then @jhodgdon.

jhodgdon’s picture

Status: Needs review » Needs work

This is getting better -- thanks for the new patch! Still needs some work though:

1. Grammar, punctuation, spelling, proofreading:

a. search.block.html.twig
- "if you want them to use the block which performs a search" ==> change "which" to "that". [but see below, maybe this will be removed]

b. search.configuring
- "deafult" is misspelled
- " or Set as deafult specific search page." ... seems awkward wording... but see below.

c. The other topics need more extensive work so I didn't look as hard at the grammar there.

2. Content changes:

a. search.block.html.twig
- Some types of search actually require other permissions. For example, to do a search on content items, you have to have permission to view those content items, and to search users, you have to have permission to view user profiles. I think we should mention this in the permissions step.
- "... if you want them to use the block which performs a search using the configured default search page" The permission is actually needed to do any search, not just the search on the default search page
- Actually, I don't think talking about permissions really belongs in the topic about the search block. It should be in the search.configuring topic.
- We need to have more discussion of the settings that are specific to the Search block. Explain what the different settings mean -- not the ones that are common to all blocks, but the settings that are specific to just Search blocks.
- "if you wish to add another instance." should be removed. The whole topic is about displaying a search block, so we can assume they do want to display it.
- The goal "Display the search block." should probably be expanded to explain that you can display a search block on your site that lets you search any of your configured search pages, and it might be helpful therefore to link directly to the topic about configuring/adding search pages. Also the configuring search pages topic should be listed in Related topics at the top.

b. search.configuring
- "Search Pages are used for adding new search pages on your site." That is not a very useful answer to the question "What are search pages". They are pages that let you perform a search for a particular type of thing with a particular configuration... needs better wording than that but saying "search pages are search pages" is not helpful.
- Enter the <em>Label</em> name and <em>Path</em> depending on your preferences. -- I think I would word this as "Enter the desired" rather than ending with "depending on your preferences".
- You need to use the word "path" rather than "URL" in the "what is" section, to make this step more obvious.
- Last step seems out of place. How about instead having a step that says "Optionally, make this new search page be the default by .... "

c. search.managing
- Under "What is the search index?", don't start the first sentence with "It", but instead "The search index...".
- Actually that first sentence should answer the question "What is the search index?" but it doesn't. The rest of that section is confusing too. I think it needs a rewrite.
- The information about the search index needing cron belongs in the "What is" background section. The information saying you need to set up a cron task should be a step, because that is something you need to do.
- The information saying you need to configure some settings should also be a step.
- Steps need to tell you how to navigate to the page to do them.
- Some information about what it means to reindex should be in the background section. Then you can have a step about how to do it in steps. Do not mix background into steps.
- Somewhere in background section it should explain that only certain types of search (certain search pages) use the index.
- As I mentioned in my previous review #37, "I think the topic should talk about the indexing information at the top and bottom of the search admin page -- maybe one of the steps would be to look at that info (or two steps, as there are two areas) and explain how to understand the state of the index"

d. search.overview
This topic needs a rewrite. If it is a task topic, it needs to have a Goal and Steps. If it is a Section topic (which I think it is), it should not have descriptions of things to do (like permissions) -- those should be moved into the configuring topic. Please see Standards for Help Topics to learn about the difference and which headings belong in which topics.

Probably also the background information about search pages, which really is important for several of the task topics, should be moved here rather than only living in one task topic (there is information about how to decide what information to put where on the standards page too).

agrochal’s picture

Status: Needs work » Needs review
FileSize
9.39 KB
12.55 KB

Thanks for the review, here's a new patch.

jhodgdon’s picture

Status: Needs review » Needs work

I installed this patch today, and took a detailed look at the output of these topics. Looking pretty good! A few things still to fix ( See Standards for Help Topics):

a) Top-level topic is called "Overview of search". You'll notice on admin/help that other topics have titles like "Configuring this" or "Doing that". So let's call this topic "Configuring and using site search" or something like that (with an -ing verb as the first word).

b) Overview topic things to fix:

Order of headings -- the topic is supposed to have one or more "What is" headings, and then a final one called "Overview". Also we are not looking to make this topic be an overview of the core Search module. It's supposed to be the landing page for a section of topics about search. So the topic should not start out with "The search module does this".

So... What I would suggest is the following heading structure:
- What modules provide site search? [Include that sentence about the core Search module, which now makes sense in this section, and also mention contributed modules, such as Apache Solr, Sphinx, and Search API.]
- What are search pages? [Include the information currently in that section. But read through it and make sure it all makes sense -- like currently it says something about "additional settings" but it doesn't really say anything about settings in the first place.]
- What are search plugins?
- What search plugins are provided by Core modules?
- Overview of search [Probably just needs to have this sentence, from the standards: "See the related topics listed below for specific tasks."]
- Additional resources (the resource link should not end in .)

c) Configuring topic:
- permissions section -- maybe a bullet list would be easier to scan than a paragraph>
- This sentence seems awkward and redundant: "Choose Search page type, depending on the type that you want to make a search page for. ". How about just "Select the desired Search page type"?
- The permissions information in step 3 should be in the "What are the search permissions?" section at the top.
- "Click Add search page to add new search page." -- how about leaving off "to add new search page"? Seems obvious.
- Step 5 -- you might say something about additional configuration that applies to some types of search pages. For example, on Content search, you can configure content ranking.
- "clicking on Set as default." --> leave out "on".
- Step 8 -- this is an incomplete list of permissions. You've listed all the permissions above, so no need to repeat. Maybe just say "Configure permissions so that users can use your new search page". or something similar.

d) Displaying block topic -- looks pretty good! The wording could be improved slightly here and there, but it reads OK.

e) Search index topic:
- "The search index is the process of collecting and parsing the data" -- well, not exactly. Search indexing is the process, and the search index is the data.
- grammar/wording needs checking throughout this page
- Step 3 -- you also need to scroll to the bottom of the page and click "Save configuration" if you make changes [make sure this comes after all the steps that update settings]. Also... we really want to keep the background information and active steps separated. So maybe it would be better to put the information about the search throttle into a new section before Steps called "What configuration affects the search index?" or something like that?
- Step 4 - also has background about the settings that should be moved into that new section
- Step 5... I don't like starting a step with "After that". It's already a numbered list. Also, this mixes background and instructions... Probably we need a section called something like "What is reindexing?" or a sentence in the "What is the search index?" section that explains what reindexing does. Then this step can be something like "Click Reindex site if you have changed the indexing configuration.".
- Steps 6/7 -- Replace with something like "Make sure a cron task has been configured". Once the cron task topic has been committed from #3041926: Convert automated_cron, ban, dblog, syslog, system, update, and user module hook_help() to topic(s), we will add a link to that topic. But we don't want to repeat the information about how to set up cron here, and the info in the steps would only work if the Automatic Cron module was enabled anyway, and for most sites, this isn't the best option for running cron either.
- Somewhere in the background information it needs to mention that search indexing is handled during cron runs, or it won't even make sense to say you need cron configured.

agrochal’s picture

Status: Needs work » Needs review
FileSize
10.54 KB
12.45 KB

Thanks, here's new patch and new interdiff.

jhodgdon’s picture

Thanks for the patch! I'm not sure when I'll have time to review this. If you would like to help, you could review this other patch (and I'll ask on that issue that they please review yours):
#3055055: Convert appearance-related modules: breakpoint, color, layout_builder, layout_discovery module hook_help() to topic(s)

jhodgdon’s picture

I probably cannot review your new patch for a couple of weeks, sorry! Possibly someone else will review. Thanks for making the patch!

hash6’s picture

Assigned: agrochal » hash6
hash6’s picture

Status: Needs review » Needs work
FileSize
10.4 KB
1.02 KB

Removed the "Overview of Search" heading and description from the search.overview.html.twig, rest all seems correct

hash6’s picture

Status: Needs work » Needs review
hash6’s picture

agrochal’s picture

@hash6, according to @jhodgon in #47 comment:

- Overview of search [Probably just needs to have this sentence, from the standards: "See the related topics listed below for specific tasks."]

"Overview of search" is heading from the help topics standards.
Then, my patch from #48 is correct.

hash6’s picture

@agrochal Thanks for pointing out to the #47 comment , I have gone through it and below are my inputs.

<h2>{% trans %}Overview of search{% endtrans %}</h2>
<p>{% trans %}See the related topics listed below for specific tasks.{% endtrans %}</p>
See the related topics listed below for specific tasks.

would have been suggested considering we had some description to the overview topic and in the end we could have added the line "...... see the related topics listed below for specific tasks."
I see the Parts of section topic mentions using it at end of the sentence

... overview: (h2 heading, such as "Managing blocks overview") 1-3 sentences describing the tasks related to this section, ending with this sentence: "See the related topics listed below for specific tasks."

So unless we don't have sentences describing the topic , my suggestion would be to avoid having it here.

jhodgdon’s picture

In some cases, we might only have the "See the related topics" sentence in that section, if there isn't anything else to say.

jhodgdon’s picture

But usually there is something to say. Like in this case, it might be something like:

Overview of search configuration

To use search on your site, you'll need to set up at least one search page, make sure that cron tasks are being run, and make sure your site's content is fully indexed. See the related topics below for details on these tasks.

benjifisher’s picture

Assigned: hash6 » Unassigned
Issue tags: +midcamp2020

I am unassigning this issue and tagging it for MidCamp 2020. I hope we can get someone to work on it today.

ericrubino’s picture

Status: Needs review » Needs work

RKoller and I reviewed the help topics documentation. It our recommendation is to keep help information about task overviews, module overviews, and configuring modules. It should be rewritten from a perspective of a new user.

For the search.overview page, change the title of the top-level topic -- remove "and using" so it is just about configuring search. It is still module-based not task-based docs. The search.overview topic needs to be pared down to just the essential overview.

For example,

What modules provide site search?
This information should be in a task topic, not the overview. And the title should be based on what the site builder is trying to do (something like making search results more relevant) rather than the modules that will help accomplish it.

What are search pages?
This section seems appropriate for the overview page.

What are search plugins?
This section is useful for developers, not site builders. We can remove it from the Help Topics documentation.

rkoller’s picture

I've worked along with @ericrubion on the issue in the Midcamp Zoom Help Topic channel

jhodgdon’s picture

I've made a new patch. I pared the information down to 3 topics (got rid of the topic about the search block), and modified the topics so that they follow our standards and focus on tasks a site administrator would need to do and information the would need to have. Hopefully!

I did not make an interdiff file, because pretty much every line of the previous topics has changed, so it was not useful.

Take a look and see what you think -- thanks!

Version: 8.9.x-dev » 9.1.x-dev

Drupal 8.9.0-beta1 was released on March 20, 2020. 8.9.x is the final, long-term support (LTS) minor release of Drupal 8, which means new developments and disruptive changes should now be targeted against the 9.1.x-dev branch. For more information see the Drupal 8 and 9 minor version schedule and the Allowed changes during the Drupal 8 and 9 release cycles.

ketansevekari’s picture

jhodgdon’s picture

When you set up the simplytest.me site, did you apply the patch from this issue? Without the patch, the topics would not be found.

ketansevekari’s picture

The patch should be applied before I launch the sandbox....right? So, yes I did. Let me set up the site again and see. Thanks for your reply.

ketansevekari’s picture

I found the "Configuring site search" topic a bit difficult to follow. Topic URL: admin/help/topic/search.overview
I have tried to rewrite the topic for better clarity. Note that I have underlined headings for you to identify which are the headings and which is normal text.
*************************************
Comment-- Restructured the workflow for better sequence. Added a new question "what is site search". Removed the last section in earlier version called "Configuring site search overview", and distributed that content among the existing sections. --comment-end

What is site search?
-----------------
Drupal allows site search through the core Search module and the use of search pages. In order to configure site search using the core Search module, you must set up one or more search pages.

Comment-- The question about site search was missing. We directly jumped to search pages but we must start with site search as that is what this topic is about. --comment-end

What are search pages?
--------------------
The core Search module organises search into pages. Each page allows users to search specific type of content with particular configuration. When a user visits the search page, they will see the configured search pages based on their user role.

A search page consists of a search form that displays search results after the user enters the search keywords and clicks Search. You must place the search form block on pages of your site, or add the search page to a navigation menu, to give users easy access to search.

Comment-- Content under search pages is slightly modified for better wording. The second paragraph contains info put under "Configuring site search overview" earlier. --comment-end

What modules provide search pages?
-------------------------------
Search pages are provided by core modules and contributed modules.
The core modules which provide search pages are:
- Node module (for searching content pages)
- User module (for searching user profiles)
- Help module (for searching help topics)

As an alternative, you can use contributed modules to provide site search. For example, the Apache Solr and Sphinx contributed modules use third-party technology to provide site search.

For content search, ensure that the search index is configured and that the site is fully indexed.

Comment-- This is the same info as earlier. I have only restructured in the form of bullets. The last sentence contains info put under "Configuring site search overview" earlier. --comment-end

What permissions are required to use site search?
------------------------------------------
Ensure that the required permissions are set for each user role:
- The Use search permission is required use any search configured in the core Search module. This permission includes the ability to use the search form block and the search page. This permission is mandatory to enable search for a user.
- The View user information permission is required for searching users.
- The View published content permission is required for searching content.
- The Use advanced search permission provides complex filtering when performing content searches.

See "Managing user accounts and site visitors" for more information about roles and permissions.

Comment-- This is the same info as earlier. Slight modifications for better clarity. I have only restructured in the form of bullets. The last sentence contains info put under "Configuring site search overview" earlier. --comment-end

What are the limitations of using site search?
--------------------------------------
There are two main limitations of the core Search module:
- The core Search module is not appropriate for very large sites -- if you have a large site, consider using other search technologies like Apache Solr.
- For content search, the core Search module supports only exact keyword matching, which may not be the behavior that most users will expect. You can improve this by installing a language-specific stemming module for your language (such as Porter Stemmer for American English), which provides results for variations of the searched keyword. For example, a search for the word walk would match pages containing the words walk, walking, and walked.

Comment-- This is the same info as earlier. Rewrote for better clarity. I have only restructured in the form of bullets. --comment-end

**********************************************
Is it possible that I can directly update the help topic? In case a developer is incorporating these changes... then if I do it myself we can save their time.

Next I will be looking at "Configuring search pages" and "Managing the search index".

jhodgdon’s picture

Thanks for the review! Don't have time to look at it at the moment; will check in a few days.

jhodgdon’s picture

If you would like to update the topics yourself, take a look at the patch file and make a new patch in the same format. If it doesn't make sense, someone else can probably make the patch file from the text in your comments.

It would also be very helpful in your review if you could point out which parts of the topics were good and which ones you thought needed improvement - a complete rewrite is of course welcome, but it is also very helpful to see what you changed and understand why. Or if you rewrote everything, you could say that. With what you've supplied, it isn't easy to see what changed and what stayed the same.

Thanks again for reviewing!

jhodgdon’s picture

Actually, it's a bit more complicated to write topics yourself... What you would need to do is:
- Clone the Git repository
- Apply the existing patch
- Edit the help topic files in core/modules/help_topics/help_topics
- Make a new patch with the updated files and any others that were in the original patch that you didn't change

That may be a bit more than you want to learn to do, if you haven't worked with Git before...

ketansevekari’s picture

Thanks @jhodgdon. I will add comments to my text about what changed and what did not. Will do this by tomorrow.

ketansevekari’s picture

Added comments to #67. I hope you find them useful.

jhodgdon’s picture

Thanks for adding those notes!

One thought... I'm not sure if I agree that we need a section called "What is site search?". We have to assume that people have some basic knowledge of the internet and web sites. I think the idea of searching a site is a pretty basic concept that we don't need to define. Besides which, the information you've proposed to put there doesn't actually answer the question -- it is instead information that (according to our Help Topic standards and the patterns of other overview topics we've already written and committed) belongs in the "Overview" section.

Regarding the rewording in the other sections, I'll have to look at them side by side to see if I prefer the new wording or the old. The comments are very helpful though. Thanks!

jhodgdon’s picture

FileSize
10.51 KB
6.89 KB

I took a closer look at your comments, and have rewritten the search.overview topic. I took many of your suggestions (thanks!), but not all (hope that is OK). In particular, I wanted to keep the format of this topic as close to other overview topics that we have already written as possible, so I didn't agree with moving some of the information you suggested moving out fo the "Configuring site search overview" into other places. Most of your other suggestions I thought were pretty good. See what you think...

batigolix’s picture

Status: Needs review » Needs work

I applied and reviewed the patch in a local dev enironment. I checked the 5 review steps from the description and most seems to be pretty much Okay.

I did find 2 typos and have a rewording suggestions to improve readability.

"Opreations" in:

<li>{% trans %}Verify that the correct search page is listed as <em>Default</em> in the <em>Status</em> column. If not, click <em>Set as default</em> in the <em>Opreations</em> list for the correct search page.{% endtrans %}</li>

"runs" in:

<li>{% trans %}Under <em>Indexing throttle</em>, select the <em>Number of items to index per cron run</em>. A smaller number will make cron runs faster and reduce the possibility of timeout; a larger number will make sure more of your site is indexed in fewer cron runs.{% endtrans %}</li>

In this paragraph ...

<p>{% trans %}When a user visits the main <a href={{ search_url }}>Search page</a>, they will see the configured search pages that they have permission to use. Each search page has a search form on it, and the page will display search results after the user enters keywords into the form and clicks the search button.{% endtrans %}</p>

.. I would rephrase the following:

When users visit the main <a href={{ search_url }}>Search page</a>, they will see the configured search pages that they access to.
Manav’s picture

Assigned: Unassigned » Manav
jhodgdon’s picture

Thanks for the review! One note, that last suggestion in #75 should read "... that they **have** access to" (the "have" is missing). I assume @Manav is going to create a patch with these fixes -- thanks! Be sure to include an interdiff file.

Manav’s picture

Assigned: Manav » Unassigned
Status: Needs work » Needs review
FileSize
10.51 KB
4.89 KB

Suggestions applied, as mentioned by @batigolix in #75

Manav’s picture

Assigned: Unassigned » Manav
FileSize
10.52 KB
4.89 KB
Manav’s picture

Assigned: Manav » Unassigned
jhodgdon’s picture

Status: Needs review » Needs work

Thanks for the patches! Most looks good to me, but one change is not quite right:

Under <em>Indexing throttle</em>, select the <em>Number of items to index per cron run</em>. A smaller number will make cron faster and reduce the possibility of timeout; a larger number will make sure more of your site is indexed in fewer cron run.

That last "run" should be "runs". (in the search.index topic)

batigolix’s picture

Status: Needs work » Needs review
FileSize
10.52 KB

Fixes #81

jhodgdon’s picture

Thanks! The changes since #74 all look good to me, and I would be +1 on setting it to RTBC. @batigolix, since you only changed 1 character in your last patch, I think you would still be eligible to review and mark as RTBC if you think it is ready.

volkswagenchick’s picture

Issue tags: +Global2020

Tagging this for DrupalCon Global happening July 14-17

batigolix’s picture

Status: Needs review » Reviewed & tested by the community
alexpott’s picture

Version: 9.1.x-dev » 9.0.x-dev
Status: Reviewed & tested by the community » Fixed

Committed and pushed c4ae3cf414 to 9.1.x and 2ec0569840 to 9.0.x. Thanks!

Backported to 9.0.x since help_topics is experimental

  • alexpott committed c4ae3cf on 9.1.x
    Issue #3047719 by agrochal, shimpy, Manav, jhodgdon, hash6, Sarahphp1,...

  • alexpott committed 2ec0569 on 9.0.x
    Issue #3047719 by agrochal, shimpy, Manav, jhodgdon, hash6, Sarahphp1,...

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.