Add link to Update module documentation about installer settings

Thanks for your effort to figure out how this all works and for opening the issue. This is the first time I remember seeing anything about this. It seems like for the most part, those checkboxes made enough sense to enough people installing Drupal through the UI over the years. 😅

But it's hard to know if this is a problem that needs fixing, since we don't have a ton of usability testing and user research that shows what happened when people tried to use the installer. Maybe there's more confusion than we think, but the folks who are confused don't bother trying to report it here as a bug report, etc.

Yet I do wonder if it actually matters that much that people during their initial installation of Drupal know that 'Check for updates automatically' actually means 'The Update Manager module will be installed'. That's frankly an implementation detail of how checking for updates works. But end users don't need to know about that detail or care how it works. They just know that if they check the box, they will have a site that will 'Check for updates automatically'. It kind of seems like this ticket is being driven by a developer that wants to be clear on implementation specifics, yet those aren't the target audience for this interface. My unsubstantiated assertion is that the vast majority of people using this form either do not care, and/or do not have enough knowledge (yet) to understand how these checkboxes are going to work.

So mostly I believe this is heading in the wrong direction. Instead of asking "Can we make these checkboxes more explicitly explain how they're going to work?", we should be asking "are people not opt'ing-in to checking for updates automatically because they don't understand that's what 'Check for updates automatically' means?" Basically, instead of refining the descriptions to explain how they work, we should try to document that people are indeed failing to install Drupal how they want to as a result of these checkbox labels.

All that said, I'm not categorically opposed to adding some help text if it's needed. I just don't know it's needed, and generally the fewer words on a page, the better.

If we are going to change this, we'll eventually need a review by the #ux team ('Needs usability review'), but there's not enough of a concrete proposal yet for them to review. Tagging for 'Usability' for now.

Hey, thanks for your thoughts! I totally get where you're coming from – we don’t want to make the install process a headache with too much info. I just found myself scratching my head when I was trying to explain to someone new how the update thing works, and it made me think, if it's confusing for me, maybe it's confusing for others too.

I'm not trying to throw a bunch of tech jargon at folks who are just trying to get their site up and running. I just think a couple of extra words might save someone else the confusion I went through. Like, as far as I can tell this is the only check box, besides choosing a install profile that results in a module being enabled during install. It's not about the gears and bolts, but about making it crystal clear what you're getting when you tick that box.

If we're worried about crowding the page, maybe we could link to a 'What does this mean?' pop-up or a help page. This way, the info is there if you want it, but it's not in your face if you don't.

Let's try it out. If it turns out I'm the only one who was puzzled and everyone else gets it, cool, we can ditch the extra words. But maybe we'll find out that it helps a bunch of people, especially the newbies.

And I'm all for testing this to see if it really makes things better. If it does, awesome! If not, no harm done, right? We're just trying to make Drupal better for everyone, one step at a time.

I'm open to suggestions, we could document it elsewhere, I even volunteer to write it up but I don't know where to put it, and I don't like that and end user would need to go looking for it and potentially not find it, when we can lead them directly to the information.

I know from my experience, even having this conversation, I'll move on, solve numerous other problems and forget these undocumented details.

What do you say we give it a shot and see what happens?

I'm all for helping people learn and understand. There's already some fine print in this part of the installer. I'd be totally in favor of making "checking for updates" a link that goes to https://www.drupal.org/docs/8/core/modules/update/overview → (or whatever the "evergreen" version of that link should really be) and add a paragraph at the top of that page that talks about these two checkboxes during the installer. I would be shocked if that got rejected during usability review and I bet core committers would be fine with such a change. Technically, it would be a fairly "visible" string translation break, so it'd have to be in a whole new minor release of core for this to go out, but that's fine, since this is correctly classified as a 'feature request' already. Would that sufficiently address your concerns?

Thanks!
-Derek

Added the actual link from the installer as a blockquote in the 'after' section of UI changes, limit screenshot widths

MR up with the 1-line patch that generated that screenshot. 😅

Hi
Verified and tested MR !6541 on Drupal version 11
Applied patch successfully...

Testing Steps

1. Install Drupal with a Standard profile
2. Go to the "Configure site" step
3. Check for the "Update Notification" Checkboxes and help text
4. Apply the patch and check for the same

Test Result:
As per the #2, #3, and #4 discussion, instead of adding descriptive help text added the link on "checking for updates" text
Link URL- https://www.drupal.org/docs/8/core/modules/update/overview →

status remains "Need review" for more reviews and code review

Attaching screenshot for reference

Could the issue summary be updated

Refine checkbox descriptions for accuracy and clarity.

that was 1 remaining task.

And proposed solution, seems to mention a different solution

I've revised the issue summary to reflect our current direction and consensus. Here are the key updates:

Proposed Resolution: Clarified that we're enhancing the "Update notifications" section with a link to detailed documentation.

Documentation Updates: Updated the section on what the linked documentation will cover.

I've updated this issue to reflect the completion of the documentation updates discussed here. Specifically, the documentation now includes a detailed section on how selecting checkboxes during the Drupal installation process impacts the configuration of the Update Manager module.

Additionally, I've revised the "Release notes snippet" to accurately describe our enhancements. The release notes now mention not just the improvement to the description in the Drupal installation process through the addition of a helpful link but also highlight the update made to the linked documentation.

I've checked the merge request and it does exactly what we talked about – it adds a link to the installation screen that points to more info. This is a simple but useful change and everything looks good to me, code-wise.

Since I started this issue, I'm going to play it safe and not mark this as "Reviewed & Tested by the Community" myself. I think the next best step is to move it to "Needs Review" so others can take a look and share their thoughts. This way, we make sure everyone’s on board with the change before moving forward.

Thanks for that!

Usability review

We discussed this issue at 📌 Drupal Usability Meeting 2024-02-23 Active . That issue has a link to a recording of the meeting.

For the record, the attendees at the usability meeting were @AaronMcHale, @benjifisher, @ckrina, @rkoller, @simohell, @skaught, and @worldlinemine.

It looks as though the last time this part of the form was updated was #2098047: Installer ui text cleanup → . That issue removed some information that seemed like "too much".

Besides trying to avoid confusion, it is important to let people know what sort of information is being collected. On that basis, we think that the proposed resolution is a good idea.

While reviewing the form, we saw a few other things that we would like to improve. Some of the changes seem reasonable to do as part of this issue, and others can be done as follow-up issues. We leave that decision to the people working on this issue.

1. The help text applies to the first checkbox, so it should be moved to a description of that option, rather than a description of the fieldset.
2. We usually try to avoid the passive voice ("information ... is sent to"). Ideally, the sentence should be rewritten to indicate who or what is sending the information. But we do not have suggested wording, and this does not seem like a particularly bad example of passive voice.
3. For accessibility, the link text should provide enough context to suggest where the link goes. We felt that "checking for updates" does not meet that requirement. We are open to other suggestions, but perhaps the simplest solution is to add another sentence, using the title of the target page as the link text: "See the Update module overview → for more information." Or maybe use Configuring Update Manager During Installation → as the link (going to that section of the page).
4. The link to drupal.org does not seem useful, and giving users two links gives them an extra decision to make: which link to follow. Let's remove the link to drupal.org. (Also, that link does not include the "www.", so it leads to a redirect.)
5. The documentation page already says, "... in order to provide this information, anonymous usage statistics (consisting of a unique key and a list of versions of the software your site is running) are sent to Drupal.org". The new section should repeat that or refer to it, in order to explain what "anonymous information" means. The text you added includes, "... your site automatically checks for the latest updates, keeping your site secure and up to date without manual intervention", which is not accurate.
6. In order to avoid confusion, the documentation page should use the same terms as the installation form: "Site maintenance account" instead of "site administrator" or "admin user".
7. The new section of the documentation page should focus on the fact that the options on the installation form enable and configure the Update Manager module. In particular:
   • In the introductory paragraph, explicitly state that the choices can be changed after the installation process.
   • Do not repeat information on what the options do, such as how they are important for security.

If you want more feedback from the usability team, a good way to reach out is in the #ux channel in Slack.

Thanks for the UX review!

1. The link is for documentation about both checkboxes and the whole topic of "Update notifications" which is what this fieldset is. I'm inclined to leave this as-is.
2. Agreed, but yeah, not sure we can do much better. For now, untouched. Open to suggestions.
3. All makes sense. For now, added the new sentence. I think "Update module documentation" is the most self-documenting link text.
   

   When checking for updates, anonymous information about your site is sent to Drupal.org. See the <a href="@update-module-docs">Update module documentation</a> for more.

4. Totally agreed. I almost removed that before, but didn't want to "scope creep". But if we're "breaking" this translation string, we should fix as much as possible at the same time. Done.
5. 5-7 are all about the docs page, so moving those to an issue tag for now.

Updated the summary and after screenshot.

Starting to save credit: @thursday_bw for the detailed issue, docs updates, etc; myself for the MR and summary updates. I believe the UX folks all get credited in their weekly meetings, not "double credit" for each individual issue. If I'm wrong about that, let me know and I can add everyone from the list in #14. I'd credit @benjifisher for the detailed write-up in #14, but again, I don't know if that's how we're supposed to handle it these days. The duplicate screenshots in #8 weren't really helpful, although it's a new user trying to review a core change and get started, so I'm on the fence...

Technically NW for the docs updates, but back to review for more eyes to get this to RTBC.

(Also, this doc page can and will be improved after this change is committed, and I don't believe anything in #14.5-7 needs to block this from being committed).

@dww, thanks for the quick updates!

Personally, I do not like "... for more". How about "... for details"?

I spoke with @benjifisher in the #ux channel in slack about 1. The help text applies to the first checkbox, so it should be moved to a description of that option, rather than a description of the fieldset.

Here's what @benjifisher had to say

IIUC (If I understand correctly), the first checkbox enables the Update Manager module. The current text depends on whether the module is enabled or not:
> When checking for updates, anonymous information about your site is sent to Drupal.org.
That much is true whether or not you receive e-mail notifications (the second box).
...
But the link we are adding does, as you say, apply to both. Maybe the existing text should go after the first checkbox and the new text should go after the second. Or maybe that would be confusing. We need to experiment a bit.And if that seems like scope creep, then we can experiment after fixing this issue.

I have updated the issue to include a tasks to experiment with splitting out the help text, however I am open to creating a follow up. But as we are dealing with translations it is easier to manage in a single issue.
I am setting this issue back "needs work" while I take a look at the documentation and experiment with the help text split.

OK. I didn't update the issues (though I did think I had, trying again).

change status to 'needs work'

OK. You can view the changes to the Update manager module's Documentation here → in now reflects the usability team's feedback in comment #14 ✨ Add link to Update module documentation about installer settings Needs work

Updates include:

1. **Clarify Anonymous Information**: Repeat or refer to the section explaining the sending of anonymous usage statistics to Drupal.org to clarify what "anonymous information" entails in the new documentation.

2. **Consistent Terminology**: Use "Site maintenance account" instead of "site administrator" or "admin user" to align with the terms used in the installation form.

3. **Focus on Update Manager Module Configuration**:
- Explicitly state in the introductory paragraph that the options selected during installation can be changed afterward.
- Avoid repeating information about the options' roles in security or their functionality, focusing instead on how these options enable and configure the Update Manager module.

adding link to the second round of documentation changes to the issue description.

I have made changes to the merge request:

• Change help text from "See the Update module documentation for more." to "See the Update module documentation for details."
• Change help text from passive to active voice: "When checking for updates, anonymous information about your site is sent to Drupal.org." to "When checking for updates, your site automatically sends anonymous information to Drupal.org."

I have also updated the issue to reflect that those tasks are complete.
I have updated the issue to reflect that @dww and myself are in agreement to leave the location of this help text on the fieldset. It is indeed scope creep as suggested by @benjifisher and we can open a follow up item if we desire to improve on this.

I have set the status to "Needs Review"

Should the "needs documentation updates" tag be removed now? as it no longer needs the updates, they are done.

Since https://www.drupal.org/docs/8/core/modules/update/overview → has been updated I do think the tag can be removed.

Change matches the proposal and agree it's useful information.

Adding a link to somewhere else during the install would result in a pretty broken site if you leave the installer at this point. If we want to add a link here we need to open it in a new window. I think we should consider very carefully whether adding a link here and distracting someone from the install process is good UX.

Thanks for reviewing, @alexpott!

1. There's "always" been a link in this description. We're just making it more useful by pointing to a documentation page, not just Drupal.org. Apparently, not enough people have read this text, much less clicked on the link, to break their sites and have it be a problem.
2. As I understand it, opening links in new tabs is not as accessible or usable, and the recommendation is to let the user decide instead of deciding for them. However, I agree in this case it's worth forcing it since it would be a problem if they don't complete this form. Added target="_blank" to the link. It's a little strange this has to be inside the t() and translations could change it, but I don't think it's worth trying to prevent that, and there's precedent in the rest of core to do it this way (@see core/modules/system/system.install, for example)

Per my comments at #2, I agree with this:

I think we should consider very carefully whether adding a link here and distracting someone from the install process is good UX.

That's why I the UX team reviewed it. I guess they agreed that since there's already a link, making it better is an improvement. Perhaps we need a re-review of "Do we need any help text at all?".

Anyway, I rebased the MR and pushed a commit to add _blank, so back to NR.

Thanks again!
-Derek

Partly answering "Do we need any help text at all?" in #27 by quoting some of the UX review results in #14:

Besides trying to avoid confusion, it is important to let people know what sort of information is being collected. On that basis, we think that the proposed resolution is a good idea.

That's another good reason we want a link here: to address people's privacy concerns about what these installer checkboxes mean.

Cheers,
-Derek

Think the conversation about removing the links could be done in a follow up, as it may take time to discuss. This least provides a better link right now. Just my thought :)

One question on the MR.

I asked in #documentation in Slack about it. @drumm replied:

That’s already the evergreen version. The parent sections are all evergreen. The only thing 8-specific is the URL, and that’s because someone unchecked the automatic URL alias and made a shorter path, that’s now outdated. I’ll reset it

Then @hansfn added:

<rant>
Yes, all (?) core modules has meaningful, but short URL's created for Drupal 8 - example for "Configuration Manager":
https://www.drupal.org/docs/8/core/modules/config →
To get this automatic URL alias was disabled, as drumm says.
The new, automatic URL for "Configuration Manager" will become:
https://www.drupal.org/docs/core-modules-and-themes/core-modules/configu... →
This is so long that I prefer that we use NID URLs instead - short and never changing:
https://www.drupal.org/node/2866146 →
</rant>

So for now, pushed a commit to use https://www.drupal.org/node/178772 → as the URL.

Editing that node, I notice a couple of other redirects all get you there:
handbook/modules/update
documentation/modules/update
docs/8/core/modules/update/overview

The numeric nid seems best, so that's what I went with. But if we need it to be an alias, I think I'd vote documentation/modules/update.

Y'all tell me what you want and I'll fix the MR to match.

Thanks!
-Derek

I don't see a problem with linking to https://www.drupal.org/node/178772 → it cuts to the chase. I don't see any usability issues as the link text
is already semantic. This URL is indeed unchanging so it the safest bet.

I also agree with

Think the conversation about removing the links could be done in a follow up, as it may take time to discuss.

Let's discuss that in a follow up. By using https://www.drupal.org/node/178772 → as the href in this issue we can move
the conversation about what the best alias is for updates module page out into the documentation page too and get this issue closed off.

Derek, thanks for your work and keeping up to date and on top of this.

Link still seems like a good improvement, if desired I can open a follow up about fully removing.

Committed and pushed 2e08112eaa to 11.x and 6205fb5e14 to 10.3.x. Thanks!

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