Convert big_pipe, dynamic_page_cache, page_cache module hook_help() to topic(s)

+++ b/core/modules/big_pipe/help_topics/big_pipe.info.html.twig
@@ -0,0 +1,5 @@
+<p>{% trans %}Module BipPipe is used to speeding up your site and it not requires any configurations. Every part of the page contains metadata that allows BigPipe to figure this out on its own.{% endtrans %}</p>

Is this correct English? Sounds very weird to me.

Here is the hook_help() module overview topic for this module that we are trying to replace:

$output = '<h3>' . t('About') . '</h3>';
      $output .= '<p>' . t('The BigPipe module sends pages with dynamic content in a way that allows browsers to show them much faster. For more information, see the <a href=":big_pipe-documentation">online documentation for the BigPipe module</a>.', [
        ':big_pipe-documentation' => 'https://www.drupal.org/documentation/modules/big_pipe',
      ]) . '</p>';
      $output .= '<h3>' . t('Uses') . '</h3>';
      $output .= '<dl>';
      $output .= '<dt>' . t('Speeding up your site') . '</dt>';
      $output .= '<dd>' . t('The module requires no configuration. Every part of the page contains metadata that allows BigPipe to figure this out on its own.') . '</dd>';
      $output .= '</dl>';

So it sounds like the topic we really need would be titled "Speeding up your site", and the instruction would be something like "One way to speed up page loads for your site is to install the core BigPipe module".

Let's make that the topic, and locate it in the help_topics module instead of in the big_pipe module. The reason for that is that if we put it in the big_pipe module area, then no one will be able to see the topic without first installing the big_pipe module, which would make the topic kind of useless. But if it's in the help_topics module area, then it allows people to learn about the existence of this module, and in another issue, we could also later add to the topic with more information about how to speed up a site.

Thanks!

Sorry for the confusion! We need the patch to be here on this issue. But it should add its topic file under core/modules/help_topics/help_topics. Thanks!

Looks good! Simple and clean, and we can always add more to the topic later. Good choice of topic file name too. Thanks!

I haven't tested that the help topic is visible and formatted OK (I just read the code in the patch), so I am not yet marking this RTBC. Adding Novice tag to see if someone else wants to test.

Don't worry about the test failure. Until the parent patch has been committed to core (which will hopefully be soon!), there is no way this patch will pass tests.

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...

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

Adding some more modules to this task.

Updated issue summary with better instructions/guidelines

Some new guidelines again. Please check out the new issue summary. Thanks!

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

Tagging this for badcamp2019. (October 2-5)

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.

Tagging for amsterdam 2019 event.

I am going to work on this.

Have changed the name of the speed help topic file to be consistent with the other help topic files.

Have added 2 new help topic files based on the hook_help method of each module.

To test this make sure the modules are enabled (big_pipe, dynamic_page_cache, page_cache)

And then go to the URL: "/admin/help"

Hi, I'll be testing/reviewing the patch.

Hi, I'll be reviewing the patch.

1. --- /dev/null
   +++ b/core/modules/help_topics/help_topics/help_topics.big_pipe.html.twig
   

   File names must be MODULENAME.TOPICNAME.html.twig, without the prefix help_topics

2. +++ b/core/modules/help_topics/help_topics/help_topics.big_pipe.html.twig
   --- /dev/null
   +++ b/core/modules/help_topics/help_topics/help_topics.dynamic_page_cache.html.twig
   

   File names must be MODULENAME.TOPICNAME.html.twig, without the prefix help_topics

3. +++ b/core/modules/help_topics/help_topics/help_topics.dynamic_page_cache.html.twig
   --- /dev/null
   +++ b/core/modules/help_topics/help_topics/help_topics.page_cache.html.twig
   

   File names must be MODULENAME.TOPICNAME.html.twig, without the prefix help_topics

Hi, thanks for the patch.

I agree with #30 that the path should be changed. As said in the summary above, the path should be:admin/help/topic/[MODULENAME].
Also in issue https://www.drupal.org/project/drupal/issues/3047703 the path was also admin/help/topic/[MODULENAME].

Also, please read the information in the Help Topic Standards page about how to divide the help information into topics. We want our information to be task-based. We don't want to end up with something just like the existing hook_help() that gives us module overviews. And the structure of the topics also does not match our standards for Help Topics. This is just a copy/paste of the hook_help and that is not what we want. Thanks!

Hi jhodgdon

I have created patch for bigpipe and dynamic page cache and page cache modules. i am trying to dived topics can u suggest me, because of this 3 modules there is no that much configuration process. Please review

Please, when you make a patch, set it to Needs Review, which will launch the test automatically, and if it fails, it will automatically set the issue to Needs Work. If you add the test manually, that doesn't happen. Anyway I will wait to review the patch until it at least passes the tests. Thanks!

#36 I will do like this onwords thank you i am trying to fix error i will make another patch.

#39 h2 tag syntax error coming i solved that please review. can u suggest how we can dived topics actually this modules does not contain much configuration.

Yes, my suggestion would be to make 1 top-level overview topic in the "core." filename space, called something like "Speeding up your site". Describe the 3 modules and what they do in that topic. And since there is only really 1 task here (doing the configuration for that), I think I would go ahead and put the Goal and Steps also in this same topic, and put in the Steps everything you can do on that admin/config/performance page. If some of it pertains to just one module being enabled, you can say something like this in one step: "If the Foo Bar module is installed, ...".

I took a pass at the overview section described in #44.

Thanks for the new patch!

We have some tests in place for Help Topics, and apparently the core.performance file does not have all of its text translated. It looks like the part that is untranslated is in the Additional Resources section (the link text needs to be translated).

I also took a quick look at the patch. A few notes:

1. The section called "Overview" -- the section is needed, but it needs a new title. See Standards for Help Topics for more information about the headings in task topics.
2. Also read about describing navigation in the Standards and fix On the Admin > Config > Development > Performance page so that it matches the standards
3. Generally I don't think the Steps are really steps. Each step should be an action, not an explanation.

Since there has been no response for a few weeks... Here is a new patch. I simplified what was in the previous patch down to a much more concise topic, which I think still conveys the essential information. I didn't make an interdiff, because pretty much every line of the file changed.

I have taken a look at patch #48 and here are a few thoughts and suggestions about the "Optimize site performance" help topic.

- If you start from the perspective of a novice user and enter the top level topic "Optimizing site performance" in his or her shoes you would expect actionable task descriptions instead he or she is confronted with two questions at first; what is caching and what is file aggregation? Well each is provided with an explanation but if the user hasn't a certain degree of background knowledge that step might be a bit too abstract and detached from the top level topic. Instead writing what the gist of "Optimizing site performance" is - simply to make the site faster (the load times as well the perceived performance) for anonymous as well as logged in users. That is accomplished by caching and file aggregation out of the box. I would mention that in most parts there is no need for configuration. And also name and briefly explaining the available parts in the introductory gist part instead of the "What can I do to improve my site's performance?" part. And maybe link to the additional documentation for the caching modules maybe inline instead of as additional resources underneath. So it isn't detached and separated.

- For the only available task to describe I would describe aside where to find those settings also what they are actually good for. Meaning what effect has "no caching", when to choose a shorter max age and when to choose the maximum age of 1 day. And also when does it makes sense to switch of the aggregation of CSS and JS files and when not to. Just to provide some explanation and context about the effect and thoughts behind those settings.

- I've also entered the text in http://www.hemingwayapp.com and the readability level for a few sentences is still hard to very hard. Overall readability score is labeled as good.

Thanks for the review!

The "What is" format is part of our help topic standards. We do not want to mix concepts into the steps -- that is not considered good practice for technical writing in general. There are 2 ways to do that: (a) have a separate overview topic with the concepts and (b) have a separate section within the task topic. Our standard says if there is only 1 task we should do (b). So that is what is done here. The structure needs to stay as it is, unless we go back and change the standards, which we could do later but right now would really derail the whole process.

Apart from that question, I'm finding it difficult to take your review and act on it... Can you provide any specific suggestions of which sentences or steps you think need to be rewritten, and make bullet points rather than a rambling complaint? I just can't process what you've written, sorry!

At first thank you for the feedback and a big sorry I got into rambling. That wasn't intended at all! I hope I now slowly get the ideas behind the concepts you've crafted out (Reading up on that one again helped). Always tended to slip in my own ideas for improvement. But you are totally right with the following point:

unless we go back and change the standards, which we could do later but right now would really derail the whole process.

So I try to stick to the current standards to speed the process up. I try to rephrase the suggestions:

- Perhaps add another help topic upfront like "What is site performance" explaining what is there in Drupal to accomplish that the site loads faster for anonymous as well as logged in users (load times as well the perceived performance). And that this is accomplished by caching and file aggregation out of the box in most parts with zero configuration.

-> Intention is bridging the gap between the abstract site performance in the headline and the questions "what is caching" and "what is file aggregation". So that not that tech savvy people know site performance is accomplished in Drupal mainly by caching and file aggregation with up to zero configuration explained in the topics afterwards.

- I've missed comment #44 where you've explained your reasoning behind "What can I do to improve..." so most of the other changes I suggested aren't valid anymore. The structure is good the way it is!

- Reduce the length of sentences. Perhaps split up longer sentences where applicable to further improve readability (Especially the caching and file aggregation paragraphs are highlighted in the http://www.hemingwayapp.com). One example:

Before:
Caching is saving already-rendered HTML output and other calculated data for later use the first time it is needed, so that the next time the same data is needed it can be quickly retrieved instead of recalculated.
After:
Caching is the storing of pre-rendered HTML output and other calculated data. Once that stored data is needed it can be retrieved instead of being recalculated.

Thanks for the more concrete suggestions... some thoughts:

1. You cannot assume that things will be set up "out of the box". Not everyone installs with the Standard profile -- they might have used Minimal or a distribution, and some of the modules and configuration may not be installed and/or set up for site performance if they didn't use the Standard profile, or they may have uninstalled modules, or inherited a site someone else already configured. I would not like to tell people that they should already have these things working, if they require a particular Core module to be installed -- they may have turned it off or not used the Standard profile.
2. I assume that the phrase "site performance" would be understood without further explanation, which is why I didn't have a section "What is site performance".
3. There is already a section on the page called "What can I do to improve site performance", which lists the modules you can turn on (if they're not already on) etc. But you cannot read that site without understanding cache and aggregation, which is why the topics on that page are in that order.
4. OK, the sentence length could be reduced. But you have actually changed the meaning in the example you gave -- slightly anyway. In the sentence that is there, the word "so" is used to indicate the relationship between the first part "what is cache" and the second part "why is it useful". The second example is I think less clear (especially the second sentence is awkward!) and doesn't show that relationships as clearly. There may be a way to separate it out into two dependent sentences, but I'm not sure that it really buys you anything in readability or understandability, just because an online tool suggests it?

So... right now I'm not sure what I would want to do to improve these topics...

On second thought... I've made a few changes that should improve the readability (by shortening sentences), and I also added a section to the top called "What is site performance".

Sorry, typo -- trans vs. endtrans at the end of thls line

+<p>{% trans %}Site performance, in this context, refers to speed factors such as the page load time and the response time after a user action on a page.{% trans %}</p>

Here's a hopefully fixed patch. Not on my computer where I can test this right now, sorry!

Looks great to me :-)

Committed and pushed 8b9b1304b5 to 9.1.x and 14afd1cbe5 to 9.0.x and 4ad4f0b226 to 8.9.x. Thanks!

Backported to 8.9.x since this is an experimental module and this is only text.