Review all pop-up messages shown by the Svelte UI installer for user friendliness

I agree "the temporary area where Composer stages its work" is more descriptive than "staging area", but I'd be concerned that if "staging area" isn't meaningful to someone, it's still just gobbledygook with more words. Will people understand Composer, for one thing? And I'm not sure that "locked" and "unlocked" will be any more meaningful to them.

I'll try to run through the messages, but I'm not 100% sure of the context they all appear in, so I'll try to explain the my understanding of the context.

1. Is this message saying the staging area needs to be locked before running Project Browser, and it isn't, or that it is trying to lock the staging area but it couldn't? It's not clear which, or what the user should do about it.

2. This sounds like an information message saying the staging area is unlocked. I'm not sure from this context whether it will be clear to the user whether that is a normal state of affairs. The original message seems too terse, but Chris's feels like it adds words without adding much meaning. I would like something indicating whether things are proceeding normally or not.

3. This message seems both clear in telling me that it couldn't download the module, but a little unhelpful in that it doesn't really tell me what's wrong. Is my internet connection down? Is the server offline? Do I need to input the server to download from somewhere?
Chris's version again feels like it's adding words without being much more helpful. Does it need to contain the project ID twice?

4. I'm wondering when would the security coverage have been revoked? Ideally we shouldn't be showing the Install button unless there is a safe version to install. If so, this message should only show if the coverage was revoked between the page displaying and clicking install. Good to cover that possibility, though.

5. This seems clear. Would it be worth including something like "This could be caused by something else running Composer at the same time."?

6. The expired staging area message seems fine, but perhaps a future enhancement could be to streamline this process, as clicking the link then rerunning the install seems a bit convoluted. It would seem cleaner to just have a pop-up ask something like, "Staging area expired. Would you like to unlock and try again? Yes/No".

7. This is one that's not clear to me what to do to resolve. Should it include something like "check with your server admin before trying again."

8. Seems okay, but I'd worry that people will just click the link without reading. A possibly future enhancement could be to add a checkbox with "I understand the risk" or similar, and not make the link clickable until it has been checked.

9. This seems safer, but still seems a little risky. Could consider the same checkbox enhancement as 8.

10. Nothing wrong with this, but I might rephrase something like, "Another project installation is in progress at present. Please wait for it to complete before installing %s."

11. This is fine, but including the project name twice seems unnecessary. I'd favour something like, "Success! Project @project downloaded and installed."
Also, I don't think it's MVP, but a future enhancement could be to list any dependent projects installed.

the install process is split into two parts, first the add part (a module is added via composer require to the file system) and then the install part (a module is installed into drupal). @chrisfromredfin confirmed on slack in the #project-browser channel that message 1 to 10 are in the context of the aforementioned add step. the terminology for add and install was agreed on in #2888657: [meta] Less confusing and more consistent wording needed in module/theme add/install/update → and was already minded for the buttons in the project browser interface (for example in #3312289: Svelte UI for install controllers → ). That terminology should also be minded for the error messages listed in the issue summary.

A few general comments. As @benjifisher mentioned in #6 📌 Review all pop-up messages shown by the Svelte UI installer for user friendliness Needs work the terminology with terms like staging area, temporary area, composer, and composer require are sort of challenging, complex, and potentially overwhelming with the audience in mind.
I've tried to avoid those specialized term but in the end completely leaving out the concept of a staging area made the error message in question even more lengthy. in the current draft i've left just term staging error in. even though someone doesn't know that staging area is used in the context of composer in this case it still communicates it is an area something is prepared. it saves a lot of explanation and still sets the context for the rest of the error messages it is used in. aside that i've changed the term install to add to be in line with #2888657: [meta] Less confusing and more consistent wording needed in module/theme add/install/update → . plus i've tried to stay specific using the term module instead of project. project is a too broad and generalized term. at the moment modules are the only project type managed by project browser but the plan is to add recipes and themes in the future as well as i remember correctly and @lostcarpark confirmed on slack. plus the label and the placeholder of the search field in project browser is using the term module as well. it might be worth a thought to adjust the h1 on the project browser search page and change it from Browse projects to Browse modules. Since the context of the top level menu item extend is about modules, projects is a too generalized term. The draft i came up with:

1. The staging area cannot be unlocked while the module is being added.

Q: I went with the definite article the module instead of the indefinite a module. if i understand correctly the error message shows in the process of a user wants to install the module of choice. with the indefinite article it might be that it could also be a module installed in another process.

2. The staging area has been unlocked. New modules can be added again.

I've added a suggestion in the second sentence for a follow up action compared to the versions in the issue summary and #4 which simply described the current state.

3. Unable to download the $project_id module from any available source.

4. The project_id module is not safe to add because its security coverage was revoked. Learn more on the [documentation page].

5. The staging area was locked by another process outside of Project Browser. Modules can be added again once the area is unlocked.

6. The staging area for Project Browser has been locked after its right to use it has expired. Use [+ unlock link] to unlock the staging area and try to add the module again.

7.
* The process for adding the module was locked @minutes minutes ago. It should not be unlocked while changes are being applied to the site.
* The process for adding the module was locked hours hours, @minutes minutes ago. It should not be unlocked while changes are being applied to the site.

8. The process for adding the module that was locked @minutes minutes ago might be still in progress. Consider waiting some more before using [+unlock link].

9.
* The process for adding the module was locked @minutes minutes ago. Use [+ unlock link] to unlock the staging area.
* The process for adding the module was locked @hours hours, @minutes minutes ago. Use [+ unlock link] to unlock the staging area.

10. The request to add the %s module was ignored. There is already another module being added.

Q: is there a recommended followup action in that case? just wait and retry after a while or do something else?

11.
* @project module was added successfully.

* @project module was installed successfully.

i've changed downloaded to added to be inline with #2888657: [meta] Less confusing and more consistent wording needed in module/theme add/install/update →

chrisfromredfin → credited anmolgoyal74 → .

chrisfromredfin → credited worldlinemine → .

chrisfromredfin → credited simohell → .

chrisfromredfin → credited ravi.shankar → .

@ralf:

1Q: Yes, Project Browser could be used by multiple users simultaneously technically, so it's possible that User B is installing a module and User A is trying to install something, so it could be very hidden from them. Maybe something along the lines of
"A module is already being installed. Please wait and try again in a few minutes."

2: ✅

3Q: I don't see how this could be improved, unless we can pass through a further error from behind (from composer). As the code is not currently doing that, it seems like it's pretty fatal. I think someone would have to adjust composer repositories or something in order to make this work. I could see this happening if we enable a repo of private modules, then try "composer install myprivate/custom_module" but the composer.json doesn't have the private repo added in it. If anything, *possibly* adding "Please check (update?) your composer.json and try again." I would have to look deeper at the code to best understand when this error could happen, so can't commit to adding the second sentence.

4: "on the" => "at" is my only suggestion here, as I assume that will just be a link to a d.o page.

5: We could also encourage them more specifically here, like "Try again in a few minutes." or something.

6: "The staging area for Project Browser has been locked after its right to use it has expired." => "The staging area for Project Browser is currently locked, but that lock has expired." (then the rest)

7: ✅

8: "might be still" => "might still be" & "some more" => "a few more minutes"

9: ✅

10: "The request to add the %s module was ignored because there is already another module being added. Please wait a few minutes and try again."

11: ✅

chrisfromredfin → credited bnjmnm → .

thanks for the review @chrisfromredfin. i've updated the suggestion. for messages that introduce something new or different to the given version i've added comments. and i've removed the term "please" from the drafts to be inline with https://www.drupal.org/docs/develop/user-interface-standards/interface-text →

1. The staging area cannot be unlocked while another module is being added. Try again in a few minutes.

comment: i've left the detail about the staging area in, otherwise this error message is interchangeable with message number 10 and you would be unable to distinguish between the two. i've simply changed the to another communicating it is about the install process of another model and not the current. plus i'Ve added the Try again in a few minutes pattern at the end.

2. The staging area has been unlocked. New modules can be added again.

3. Unable to download the $project_id module from any available source. Try again in a few minutes in case the error was due to a server downtime. If the problem persists, check your site's composer.json if all the repositories selected in Project Browser are entered there as well.

comment: based on your answer i've added the point that the user should wait a few minutes at first and try again. ruling out the case that for whatever reason the remote server was down the source should have been pulled from. for the next sentence due to the fact that it is the most fatal possible error i went a bit more technical and added in case the problem persists it should be checked if the repositories set in project browser are entered in the site's composer.json as well. based on the potential scenario you've outlined. i've decided against something like contact your administrator or something like that. for one you are not sure if the person reading that has an admin or even an admin team at all. that way the user is at least provided with potential cues where to search online or provide someone tech savvy to help.

4. The project_id module is not safe to add because its security coverage was revoked. Learn more at the [documentation page].

5. The staging area was locked by another process outside of Project Browser. Modules can be added again once the area is unlocked. Try again in a few minutes.

6. The staging area for Project Browser is locked, but that lock has expired. Use [+ unlock link] to unlock the staging area and try to add the module again.

7.
* The process for adding the module was locked @minutes minutes ago. It should not be unlocked while changes are being applied to the site.
* The process for adding the module was locked hours hours, @minutes minutes ago. It should not be unlocked while changes are being applied to the site.

8. The process for adding the module that was locked @minutes minutes ago might still be in progress. Consider waiting a few more minutes before using [+unlock link].

9.
* The process for adding the module was locked @minutes minutes ago. Use [+ unlock link] to unlock the staging area.
* The process for adding the module was locked @hours hours, @minutes minutes ago. Use [+ unlock link] to unlock the staging area.

10. The request to add the %s module was ignored because another module is already being added. Try again in a few minutes.

comment:i've slighty altered the version you've suggested. i've remove the "there is"

11.
* @project module was added successfully.

* @project module was installed successfully.

I think everything we have is really good here except #3.

You had:
Unable to download the $project_id module from any available source. Try again in a few minutes in case the error was due to a server downtime. If the problem persists, check your site's composer.json if all the repositories selected in Project Browser are entered there as well.

Suggest:
Unable to download the $project_id module from any available source. This might be a network issue, so you can try again in a few minutes. If the problem persists, check your site's composer.json to be sure the project is available to Composer.

Hopefully that's a bit simpler, even if it's not perfect.

added the final revision of error messages to the proposed resolution in the issue summary. the final discussion happened over at https://drupal.slack.com/archives/C01UHB4QG12/p1678823937755859 . adding the needs usability review tag and i will add the issue to the usability meeting queue.

We've discussed this issue at 📌 Drupal Usability Meeting 2023-06-02 Fixed . That issue will have a link to the recording of the meeting.

For the record, the attendees at the usability meeting were @benjifisher, @blackbamboo, @rkoller, and @simohell.

The main recommendation previously voiced in #6 📌 Review all pop-up messages shown by the Svelte UI installer for user friendliness Needs work to avoid any kind of reference to terms like "staging area" or "temporary area" still stands. (*One addition from me as someone working on the word smithing in this issue before the review. It was a deliberate decision that i've suggested keeping the term "staging area" in, see #8 📌 Review all pop-up messages shown by the Svelte UI installer for user friendliness Needs work . Paraphrasing what is actually happening avoiding any of the aforementioned terms became way too wordy and using "staging area" was brief and not necessarily specific to composer in my eyes.). During the discussion the group came up with suggestions for the first two messages how to avoid the term staging area in an acceptable manner.

1.
Change
The staging area cannot be unlocked while another module is being added. Try again in a few minutes.
to
Another module is being added. Try again in a few minutes.

2.
Change
The staging area has been unlocked. New modules can be added again.
to either
System ready, you can add a new module again.
or
Project Browser ready, you can add a new module again.

It might be confusing to the user what System refers to therefore an alternative option to consider might be using the modules name Project Browser.

3. The third term was fine with the group as is.

The first two suggestions provide a good cue to improve the rest of the messages by removing the term staging area in a similar manner. I'll set the status back to Needs work and will post a suggestion for the rest of the strings that need a update either later tonight or tomorrow during the day.

p.s. one question when i was going through the rest of the strings before writing up this comment. what is the exact difference between message 1 and 10? over the course of the last few comments both communicate more or less that another module is currently installed alongside. but revisiting #4 📌 Review all pop-up messages shown by the Svelte UI installer for user friendliness Needs work the meaning sounded different:

1. Install cannot continue. The temporary area where Composer stages its work needs to be locked while it is applying changes, but it is unlocked.

but in the explanation in #14 📌 Review all pop-up messages shown by the Svelte UI installer for user friendliness Needs work the meaning turned into:

1Q: Yes, Project Browser could be used by multiple users simultaneously technically, so it's possible that User B is installing a module and User A is trying to install something, so it could be very hidden from them. Maybe something along the lines of
"A module is already being installed. Please wait and try again in a few minutes."

so not exactly sure if one of the messages is redundant or if the gist of the first message should be different?

The difference between 1 and 10 is what action causes them. In #1, the use is requesting an unlock of the staging area, but we're saying "no we can't unlock it while a module is being installed."

In 10, the user is requesting to install a module, but we're saying "we can't install a module while a module is being installed."

So they're the same effect, different cause.

Usability review

We discussed this issue at 📌 Drupal Usability Meeting 2024-06-28 Needs work . That issue will have a link to a recording of the meeting.

For the record, the attendees at the usability meeting were @AaronMcHale, @benjifisher, and @rkoller.

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

Initially our main objective was trying to solve the problem with the third error message. As mentioned in #19 📌 Review all pop-up messages shown by the Svelte UI installer for user friendliness Needs work and #8 📌 Review all pop-up messages shown by the Svelte UI installer for user friendliness Needs work it should be tried to avoid using technical terminology like staging area, composer, and alike.

Our first idea was, in case error three takes place to write a more verbose entry to the log file and go with something like this:

Unable to download the $project_id module from any available source. Try again in a few minutes. If the problem persists, see the logs for more information.

That keeps the error message itself easier to comprehend, and it is pointing the user to the logs, the only problem it won't provide direct actionable instructions how to solve the actual error. But the user would have at least some clue that one could post in a support forum.
Another idea we then came up with is, making what is actually happening, a bit more explicit with the error message, by stating that the project is unavailable in the repos which are defined in the sites composer json, and then pointing the user again to those logs:

Unable to download the $project_id module from any available source. Try again in a few minutes. If the problem persists, make sure that $project_id is available from at least one repository in your site’s composer.json. See the logs for more information.

Problem here, the terms repository and composer.json might be too challenging and too technical for none technical folks. For the "see the logs" sentence the same problem applies like for the first idea. In the end we ended up on a consensus to the following third idea:

Unable to download the $project_id module from any available source. Try again in a few minutes. If the problem persists, see Project Browser: Troubleshooting. (*with something like #no-available-source in the link)

It is basically impossible to explain everything in plain (none technical) english within one or two sentences. Therefore, since from my understanding this error message is for an advanced edge case using an additional (private) source, the regular user browsing and installing projects from d.o won't ever run into that, we thought it might be the best compromise to create a troubleshooting page specific to that problem. The link in the error message should directly point to the to be created troubleshooting section. In that troubleshooting section the problem should be briefly explained and then more importantly outlined how to actually fix it.

We then went ahead and copied the current state of all 11 error messages to a google doc because we've noticed that there is the need of a consolidation of the rest of the error messages. Some are still using the term staging area, and then there is the question should the term Project Browser be used in the micro copy at all. @benjifisher raised the valid point that if you the user are just click through project browser you have the h1 of "browser projects" and some of the status messages contain "project browser" (but both are fyi status messages informing the user that a dev version is being used). So the question is has a regular none admin user who has no permissions accessing the extend page is familiar with the concept of project browser?

We agreed to move the discussion of the last details over into the google docs document. The link is the following: https://docs.google.com/document/d/1SEjq-UkbCQglh7DTIJw1_rk2ckDo8qk8tV7m...

Tried to start with this as creating an MR makes it easier for reviews.Some of the messages mentioned in the IS are now obsolete,we must update the IS.

This issue is now ready for reviews.The only test that's failing is also failing for other branches and is a problem on 2.0.x.Except that all tests are passing.Marking it NR for reviews.

Hello good afternoon, my suggestion would be this:

The staging area cannot be unlocked while another module is being installed. Please try again shortly.

The staging area has been unlocked. You can now add new modules.

Unable to download the $project_id module from any source. This might be due to a network issue. Try again in a few minutes, and if the issue continues, check that the project is available to Composer in the site's composer.json file.

The $project_id module cannot be added due to revoked security coverage. Learn more in the [documentation page].

The staging area is currently locked by another process outside Project Browser. You can add modules once the area is unlocked. Please try again shortly.

The staging area for Project Browser is locked, but the lock has expired. Use [+ unlock link] to unlock and try adding the module again.

The module installation process was locked @minutes minutes ago. Do not unlock it while changes are being applied to the site.
The module installation process was locked @hours hours, @minutes minutes ago. Do not unlock it while changes are being applied to the site.
The module installation process was locked @minutes minutes ago and may still be active. Consider waiting a few more minutes before using [+ unlock link].

The module installation process was locked @minutes minutes ago. Use [+ unlock link] to unlock the staging area.
The module installation process was locked @hours hours, @minutes minutes ago. Use [+ unlock link] to unlock the staging area.
The request to add the %s module was not processed because another installation is already in progress. Try again in a few minutes.

The @project module was successfully downloaded.
The @project module was successfully installed.

@utkarsh this is a big step in the right direction; thanks for also starting the MR - it does make it easier to review.

I think I want to get rid of all references in user-facing language to "staging area" - but I like the "process" language that is used. I have put comments in the MR.

Moving back to "Needs work" for the changes to the "staging" language that @hrisfromredfin added to the MR.

Made the changes requested to replace the staging area with the suggestion given by @chrisfromredfin. Marking it NR again.

I've reviewed the changes and can confirm all instances of "staging area" have been replaced. It could always be futzed with more, but this seems like it's been thoroughly de-jargonized.

Merged the latest changes from 2.0.x.This is ready for review again.

The changes look good to me. We can improve them later if needed, but I think this is good to go for now.

We discussed this issue another time at 📌 Drupal Usability Meeting 2024-11-29 Active . The recording of the meeting can be found at https://youtu.be/l1rxLBree2c. For the record, the attendees at the usability meeting were @AaronMcHale, @benjifisher, @rkoller, and @simohell.

Apologies I haven't managed to write up a summary earlier. I've only provided the brief gist of the discussion on a thread during the meeting for project browser on the drupal slack last wednesday.

We've started to compare the current state of the MR with the artifact, the google doc (https://docs.google.com/document/d/1SEjq-UkbCQglh7DTIJw1_rk2ckDo8qk8tV7m...), from our last discussion of that issue. it has to be noted that we've only managed to cover the first string during that one hour. the noun “project” pulled us into a rabbit hole (i would recommend watching the video for the broader outlook). but the scope for this summary is limited solely to the details directly relevant to the popup messages.

When we've discussed the first popup message the last time, we've ended up with Another module is being added. Try again in a few minutes., the current MR only changes the term module to project for that string. We understood the point, that for probably technical reason a specific term like module was avoid within the popup messages to circumvent any complexities by using a more general and neutral term that is able to cover and describe not just a single source type.
But there was a clear consensus in our group that going with the term project in this case is sort of problematic. Project is a term that is used in the context of drupal.org, but in the context of drupal core the concept of a project is not really used in the micro copy of the admin UI, even the user has no real touch point with the module name of "project browser" (except the persons who have access to /admin/modules). You encounter the term project only in the popup messages this MR introduces and the prominent h1 Browse projects on admin/modules, in drupal core people are more familiar with the concept of extensions instead (also reflected in the the top level menu item Extend).
In summary project is a term used in the context of drupal.org but not anywhere in drupal core, which might lead to potential confusion and a higher cognitive load, which is in particular relevant if you run into the concept of a project in the context of a stress case like an error. So if you wanna go with a more general term, we we would recommend going with the term extension instead of project in the installer messages, as well as to consider changing the h1 on /admin/modules from Browse projects to Browse extensions.

And it would be good if @chrisfromredfin could maybe join the next usability meeting or one after, then we could revisit the issue and go through the rest of the strings. it is always better to have someone joining the discussion who knows the underlaying technical ins and outs. that way we might hopefully finish the rest of the strings and finally commit this.

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

I think we need to push the idea of "project" more universally, both with "Project Browser" and in the Drupal world as well. We've always had this distinction (a project, for example, can be made up of many modules, actually). And we really are working at the project level.

This is a big step forward, so I am going to send this as is. We can revisit later if there is demonstrated user confusion.