Convert contact module hook_help() to topic(s)

Issue created for in the mentoring space at DrupalCamp Asheville

@luwoldy, @eeyorr, @CelSki, and I created this issue in the first-time contributor workshop at DrupalCamp Asheville.

We reviewed the instructions from the meta ticket and had a round-robin where each new contributor created an issue so they would understand the process.

Tagging issue for DrupalCamp Colorado Contribution Day August 4, 2019 -https://2019.drupalcampcolorado.org/contribution-day

The patch is a direct copy & paste of the hook_help() of the contact module.

This could serve a starting point for the help_topic.

Moving this into needs work as we are not looking for 1:1 copy from the module overview page.

as pre #7 in the summary
Do not just copy the text of the old module overview word-for-word. We don't want an overview of the module -- we want one or more topics that are task-centered, that would be useful for someone managing or building a Drupal site. If you need to explain a concept, put that in a separate section or sections within the related task topic, with headers like "What is/are...?" question, such as "What are actions?".

Please check out this new issue summary with new guidelines for topics.

Did some adjustments to adjust to the new help topic standards and the issue summary of this issue:
- Divided the exiting topic into a top-level section and seven tasks
- Added "Additional ressources" to section and tasks
- Used "Goal/Steps" approach in the tasks where possible
- Used "What is" approach in section
- Rewritten part of the content

Open question:
- Looking at the task "Using the personal contact form", I am not sure how to include this. Here are some information about using it as a visitor but also about permissions needed for this, and configuration of registered user's personal contact form. Any suggestions here?

Thanks for the patch! Sorry for the delay in reviewing. I must have not noticed it when you posted it, and then it slipped off my issue screen.

So... a few notes:

a) Navigation -- we have standards in ... oh wait! This issue apparently didn't get updated when we updated all the other issue summaries. So, updating the issue summary. Oh I see, the parent issue doesn't have this issue link in its issue summary, so I'll fix that too.

Anyway, on other issues, we have now developed a page with standards for help topics:
https://www.drupal.org/docs/develop/documenting-your-project/help-topic-...
One of the things there is now to describe navigating to admin pages. These topics will need an update.

b) Other standards... these are looking pretty good with respect to the other standards.

c) In general, we want to link to other help topics if possible, instead of drupal.org pages. A few reasons: the help topics are within the same site, already available, don't require a connection to the wider Internet, and also they will be translated (whereas drupal.org generally isn't). So, where you have links, for example, to the online docs about the Block module, we probably instead need to link to the block module topics (which may not exist yet, as they're being worked on in other issues). What we're doing in other issues is creating small "stub" topics to make those links live, and then depending on which issue gets done first, we'll have to modify the links in the second-to-be-done issue.

d) Goal section -- let's not use -ing verbs -- see the sample text on the Help Topic Standards page linked above. So for example, it might start with "Configure" instead of "Configuring".

e) You asked a question about the "Using the personal contact form" page... I think we should:
- Add a "What is" section to the main overview top-level topic, and explain there the difference between personal and site-wide contact forms. So maybe a section called "What is the personal contact form?"
- Add a topic called "Configuring personal contact forms" that would explain the permissions and other configuration for that
Does that make sense?

#10 as per your requirement i did some changes in help_topic contact form if you have time can you review this patch.

- I found a few typos, you can see screenshots.
- "Using the personal contact form" Steps part need some work.
- "Adding content to contact forms" Block layout page link doesn't work.
Maybe someone else has something to add.

Hii @alonaoneill Thanks for reviewing the patch and as per your suggestions I have recreated a patch , please review.

Tagging for badcamp2019, thanks! (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.

#20 i updated contact help topic patch as per new help topic standers please review.

It is very helpful to change the issue status to "Needs review" when you would like a review. :) I'll take a look at this (and some other Help Topics issues) when I can (it might be a few days though, sorry!). Thanks for the patches!

Thanks for the patches! This is looking pretty good. I have a few thoughts about the latest patch (#20):

a) In general, in "Additional resources": we should only link to online documentation if there is actually something useful there that isn't covered in the topics. I haven't checked over the pages that are linked to, but probably most of those links can be deleted.

b) contact.overview.html.twig
- "What is the contact form?" section -- there are really two different types of contact forms: personal contact forms and site-wide contact forms. I think the content of this section should be clear about that. Maybe start with "There are two different types of contact forms: the personal contact form, and site-wide contact forms." and then go from there?
- the <em>Contact</em> module in core -- we have a standard way in user interface text to refer to modules. Should be "the core Contact module".

c) contact.adding_content.html.twig
- Title -- I wouldn't call fields "content", so I think the title should be changed, and probably (correspondingly) the file name too.
- Goal -- similarly, I wouldn't say "fields and other content", but instead "fields and content", because fields are not the same as content.
- Steps -- Each topic should have steps that make sense as one OL list. So, I think the second OL list about adding content using blocks should maybe just be mentioned in the Goal section instead of having steps? It really isn't explained anyway.
- Navigation -- check the help topic standards for the standard way to describe navigation.
- Additional resources -- we do not want to send people to the online documentation for the Block module. We should be linking to a topic (which doesn't exist yet). So just leave that out.
- No newline at end of file (there should be)

So... I think for this topic, the title should be about fields only, and in the Goal section, make it about fields and maybe put in at the end "(To display text or images on your contact form page, use a block.)

d) contact.configuring_personal.html.twig -- this one looks good except for the navigation description.

e) contact.configuring_site.html.twig -- this one looks like it pretty much duplicates the instructions in contact.adding_content.html.twig... We shouldn't have two topics that say pretty much the same thing.

f) I think we need some text in some topic (probably the overview?) that explains about having multiple site-wide contact forms and how that works?

g) contact.linking.html.twig -- looks OK except navigation

h) contact.setting_default.html.twig -- looks OK except navigation. There is a typo "bellow" and some problem with em tags in the 3rd step

i) contact.using.html.twig -- the steps in this topic are not really steps... this seems just like overview information. I think this should be moved into the Overview topic.

@jhogdon

Can u review https://www.drupal.org/project/drupal/issues/3073476

If that patch is correct i will try to work on this issue as well.

Yes, I am working through these issues. Sorry -- I have been busy... I think that is the next one on my list (I am trying to do them in the order the patches were created), so I will hopefully get to it later today.

Hii @jhodgdon
Thanks for reviewing patch i re-created patch as per #24 comment suggestions please review.

Thanks for the patch!

One thing I've seen actually in a few of your patches: They have an empty file at the end at the root level called "git". That shouldn't be there

diff --git a/git b/git
new file mode 100644
index 0000000000..e69de29bb2

Probably you have that file in your local copy of the Drupal git repository. You should remove it.

Anyway, aside from that, this is looking better! I've reviewed the topics and made some changes, so here's a new patch (it was easier to do that than to make comments on what I thought should be changed). Some notes:

a) Overview topic -- I simplified this, rearranged, and moved the information about permissions to the configuring topic.

b) Configuring personal forms topic -- updated the title and added information about permissions configuration.

c) It seems like we were missing a topic about creating a new contact form. There is no point in having a topic about setting a form to be the default if you only have one. So, I added this topic.

d) I thought we probably didn't need a whole topic on linking. Instead, I added notes to the Creating and Setting default topics about URLs.

Anyway, here's a new patch. I don't think an interdiff is all that useful, since most lines from the previous patch had at least small changes to them.

1. Patch applied. Help Topics module and Book module were enabled.
2. Reviewed Help Topics for grammar and spelling. "Managing contact forms" topic has a typo "users's", I showed it in the screenshot.
3. All links work!
4. Provided screenshots with all Help topics created!

Thanks!

Thanks for the review! Here's a patch with the typo fixed (only that one change is made, I just edited the patch file).

A few remarks on "Configuring personal contact forms"

• In the sentence "check or uncheck the box to enable the contact form for new user accounts" the part "check or uncheck ... to enable ..." confuses me, but readers will probably understand what is intended
• "Anonymous user" instead of "Anonymoususer"
• "... have the correct permissions checked or unchecked" instead of "... have the correct permissions checked and unchecked"

No comments on the other pages.

Good review, thanks! I have made a few changes to address your comments (new patch/interdiff attached).

Wording may change

Wow, thanks @andypost. That will have a lot of UI implications probably on many topics, as well as the User Guide.

Hii @andypost

I have Rename 'Authenticated user' to 'logged-in user' and 'anonymous user' to 'visitor'

Please review.

That change in Core has not yet been made, so we shouldn't be updating the help topic to that yet. I think we should go back to the previous version, because we need to match what is seen in the UI. Uploading that patch again.

Yes, better to not wait for the change - we can change it later

Added a few topic cross-links, which I think improve things a bit.

I think this looks good. Thanks everyone!

bot flux

Unrelated failure with port allocation

Unrelated failure

Drupal\Tests\media_library\FunctionalJavascript\WidgetUploadTest::testWidgetUploadAdvancedUi
"image-1.png" not found

That one looks like it should have an issue, so I'll make sure there is one.

Its good to see forward this issue. Thanks everyone!

+++ b/core/modules/help_topics/help_topics/contact.setting_default.html.twig
@@ -0,0 +1,14 @@
+<p>{% trans %}Set a site-wide contact form to be the default contact form (the form that is shown on the <em>/contact</em> URL).{% endtrans %}</p>

It's possible the /contact path is altered so might not be on /contact. I think we should link to the site wide contact form using the contact.site_page route. But I think this can be improved in a follow-up. So going ahead and committing.

Committed and pushed 8fe6d250cc to 9.1.x and 97744c0922 to 9.0.x. Thanks!

I backported to 9.0.x because help_topics are still experimental.

@alexpott Thank you! I think the follow up is #3090659: Make a way for help topics to generate links only if they work and are accessible

I will also put a note on #3121340: Fix up minor copy problems in help topics for this. Thanks @alexpott!