Improve UX for uploading revisions

[NateWr]

Describe the problem you would like to solve Revisions can be uploaded, but there is no way to mark "all revisions uploaded" and no way to provide feedback to authors about what is expected from them at that time.

Describe the solution you'd like Authors should be asked to upload revisions in a wizard-like workflow that can ask them to confirm things, make additional changes, and mark their task "done".

Who is asking for this feature? Editors and admins who want to improve email notifications about revisions (currently an email is sent when the first revision is uploaded, even if the author is not done). Editors who want to request additional information from authors during revision upload. Editors who want to ask authors to confirm they've completed steps during revision upload.

Additional information The UI/UX group in the Pittsburgh sprint identified several uses to which such a workflow could be put, particularly if it could be configured on a per-journal basis:

• When the author submits revisions, this is a good time to ask them to update their metadata, for example if the title has changed. This request could be automated.
• Something like a submission checklist for revisions: have you signed our copyright form? have you responded to each of the itemized enquiries from your reviewers? etc.

[openacademia]

I just want to add my support for this improvement! The "Revised Version Uploaded" email should be triggered by the Complete button, not the Continue button (so as to not trigger several emails for the same revision).

We also have several authors feeling unsure if the are "done" as there is no clear indication that they have fulfilled the task simply by uploading a revision. Ideally, there would be a "Submit Revision documents to Editor" button or something which would signal to the author that the process is complete and they can safely log out would be good. And to have THAT trigger the message to the editor would be excellent.

[ajnyga]

A related old discussion here: https://github.com/pkp/pkp-lib/issues/3278#issuecomment-363337819

[NateWr]

From 3.3 on, it will be possible to use the REST API to upload files. This would be a good time to implement a revision upload wizard for authors.

[NateWr]

Here is a mockup for a new workflow to submit revisions. The goal is to have a dedicated page for submitting the revisions with a final confirmation step. This will ensure that:

• We can send one email to editors when the revisions are ready for review.
• We can expand this revision workflow in the future to include things like helping the author revise submission metadata, complete a revision checklist (have you done X, Y and Z), etc.
• Revision upload will have a dedicated URL. The email to request revisions can include a link sending the author directly to this page so they don't have to find the revision upload area on the author dashboard.

In the following mockup, the Revision Files grid will be removed from the author dashboard. When revisions are requested, the author sees a prompt to upload revisions.

The author is taken to a page where they can upload revisions. The author is encouraged to replace files, rather than upload new ones. And there is room for descriptive text to help the author complete the task.

The author can still upload new files.

And the author can save and come back to the revision upload process. Or if they're ready, submit the revisions.

When submitting, the author is provided with a confirmation prompt that provides information about what will happen next.

After revisions have been submitted, the prompt in the author dashboard changes and the author is provided with a link to view the revisions or upload new revisions.

This should be a significant improvement for now. In the future, we can easily expand on this pattern by turning the wizard into a multi-step process, like the submission wizard. Other steps could ask the author to update metadata, confirm that they've fulfilled journal requirements, etc. In such cases, additional steps could be added by just changing the terminology of the submit button.

The revision submission email to editors would not be triggered until the final step is completed.

[alexxxmendonca]

This looks really great, @NateWr !

Please consider adding an additional step before the uploading process where authors are asked to respond to the Decision Letter.

Many journals use this to check whether all requests made by the reviewers have been met and some even share this author's response to the reviewers themselves in subsequent rounds (specially, but not limited to, when authors' identity is open for reviewers).

[NateWr]

Thanks @alexxxmendonca, I think in the future we will be able to include additional steps like this. For now, our friends at @ubiquitypress are interested in contributing work on this for 3.4, so I'm keen to limit the scope of the changes to ensure that they're able to complete the work on time. But I know they're interested in similar features down the road.

[fradeve]

Hi everyone! After a conversation with @NateWr and within our Editorial team, Ubiquity Press is going pick this up. We have agreed on the specs as follows.

When Revisions have been requested:

1. Revisions request

(Author > Workflow > Review)

• Replace the existing 'Upload file’ button with a ‘Upload Revisions’ button on the author’s revisions workflow page. This should be in the existing ‘Revisions’ section of the page.
• The existing ‘Search’ button should be removed from the ‘Review’ section of the page

All other aspects of this Author page remain the same.

2 - Revision list

Once the new ‘Upload Revisions’ button is clicked:

• A new page opens, which lists all of the ‘Review Files' along with some descriptive text on the page to provide instructions.
• Authors can upload revised versions of existing files, delete existing files or upload new files to the list.
• At the base of the window is a: ‘Save for later’ button: saves any edits but does not alert the editor ‘Submit Revisions’ button: clicking the button should create a pop-up box asking the author to confirm that they are happy that their submission is complete and fully revised.

3 - Clicking a confirmation button then

closes the task for the author and

• sends an email notification to the assigned Editor, where the status of the submission will now be ‘Revisions submitted’. (NOTE: currently emails are sent to the editor for every file uploaded = we will need to disable this from the code)
• the Activity Log records that the revisions have been submitted and a copy of the email sent.

4 - Once the revisions have been submitted

Author:

• A text bar confirms that revisions have been submitted.
• The author can see a list of their submitted revised files via a ‘View Revisions’ button, but cannot provide additional revisions anymore

5 - Clicking the ‘View Revisions’ button

• displays the submitted file list
• provides text to say that if files were submitted in error, the author should use the Discussions function to contact the editor and provide the correct file(s).

6 - Editor view

• All files sent by the author will be available via the Review Files section of the Editor interface. This should show the full list and not only the files that have been revised/uploaded during the revisions process.

[ajnyga]

Is there a reason not to allow further changes to the files after they have been submitted? I mean having something like View Revisions -> Edit.

[twakeford]

hi @ajnyga - yep. Providing more revised files after the task has been completed can cause pretty big confusion in the editorial workflow. e.g. what if the editor has assessed the original files and discussed it with the board / has already sent the file out to reviewers who have downloaded the original version and started their review / perhaps one review has been submitted but a second review is outstanding etc.

Generally, the revisions process should have a set endpoint to avoid all such things (and also to focus the author on completing revisions as a whole and not encouraging them to drip feed files). Allowing updates post-submission increases the risk of wasted time or error on the editor/reviewer side.

Providing updates is still possible, as authors may well upload the wrong file in error or thing of something they missed, but they should do this in discussion with the editor and not be able to do this whenever they like. As such, we made sure that this was mentioned in the 'Revisions Uploaded' file list.

[alexxxmendonca]

This all looks great. Nice work!

I have just one question. I noticed that sometimes it's mentioned "Review files" instead of "Revision Files":

A new page opens, which lists all of the ‘Review Files' along with some descriptive text on the page to provide instructions.

All files sent by the author will be available via the Review Files section of the Editor interface. This should show the full list and not only the files that have been revised/uploaded during the revisions process.

I wonder if these were typos and it's actually meant to be "Revision Files"?

Just want to make sure we are all talking about the same thing.

Review Files -> Files sent by the reviewers Revision Files -> Files sent by authors after a "Revision"-type Decision.

[twakeford]

Good spot!

I think that there is an error that we will fix and also confusion in terminology.

Terminology Review Files > refers to the section title on the Editor display that lists all files in the Review process.

= The first example is correct - the list presented to the author will replicate the Review Files list. i.e the editor will pass the files that have been reviewed back to the author for them to update.

Error The second example is an error in the description - it should read 'via the Revisions section of the Editor interface. i.e. files display exactly where current revisions land for the editor, but now the full list will be shown rather than only those files that have been uploaded as part of the revisions process.

[alexxxmendonca]

Perfect! Thanks for clarifying!

[twakeford]

There is a stage not documented above that I believe also needs to be included in this work:

When the Editor currently makes the decision to request revisions, they are presented with a file list of all files in the 'Review Files' list AND any files uploaded by the reviewers as part of the review. The Editor must tick any files that they wish to share with the author (I'm not actually sure why the Review Files are currently listed, as I can't work out what ticking these does in the current workflow...)

As the author will be provided with the full Review Files list anyway as part of the Revisions process, we should remove these files from the Editor decision workflow, so that they are only selecting whether to share the Reviewer files with the author. Current Display:

Proposed Display:

The Reviewer Files will be unticked as default, so that the Editor must actively select them, meaning the risk of passing confidential or identifying information to the author is minimised.

[alexxxmendonca]

@twakeford this makes sense to me!

[NateWr]

Thanks @fradeve and @twakeford. This all looks really good! A couple of minor changes/clarifications:

Replace the existing 'Upload file’ button with a ‘Upload Revisions’ button on the author’s revisions workflow page. This should be in the existing ‘Revisions’ section of the page.

In the first screenshot there are two notifications. One at the top that says revisions requested and then one below in the revisions section with a button to ask for revisions. These should be combined so that there is only one notification at the top of the review round at any time. The revisions section can be removed from the author dashboard completely.

We should probably remove the old-style notification system that exists at the top of the review round now, and just use a <notification> at the top of the review round whenever the status suggests that one is required.

‘Save for later’ button: saves any edits but does not alert the editor

Just a minor technical clarification: each time a file is added, edited or deleted in this UI, the change will automatically be saved. The "Save for Later" button is just for the user so that they feel confident they won't lose their work.

2 - Revision list

The screenshot in this section suggests that the user can click on the component type (Article Text, Other) to change the type. If this is an important feature, then we need to add an "Edit" button to the UI. The badge UI components should not be interactive (this is something we want to enforce in the UI).

You can look at how the submissions list in the submission wizard works (type is prompted after uploaded). We should try to emulate that as much as possible so that they are consistent.

When the Editor currently makes the decision to request revisions, they are presented with a file list of all files in the 'Review Files' list AND any files uploaded by the reviewers as part of the review. The Editor must tick any files that they wish to share with the author (I'm not actually sure why the Review Files are currently listed, as I can't work out what ticking these does in the current workflow...)

This UI is kind of a mess. It feels like we've added lots of different files into the list over time, but without distinguishing between them properly. With the Review Files, if I remember correctly, these are attached to the email, but otherwise not visible in the author's submission dashboard.

I think the key thing to do is figure out which files can be shared and then display them in separate, simplified lists based on where the file is. In my view, the only files that really need to be here are the files uploaded by a reviewer. But if we offer the other files, then probably that's because some journal has asked for it, and I wouldn't want to pull it out without understanding the use case.

So my ideal approach here would be to have one checklist with only the files uploaded by reviewers. Then we can use an additional accordion toggle called "Share other files with the author" which would include two checklists, one with the Files for Review and one with Revisions (if they exist).

This is a UI that is probably going to get rebuilt in 3.4 as part of #5717. So it may make sense to leave this alone and wait to see what happens.

[alexxxmendonca]

So my ideal approach here would be to have one checklist with only the files uploaded by reviewers. Then we can use an additional accordion toggle called "Share other files with the author" which would include two checklists, one with the Files for Review and one with Revisions (if they exist).

+1

[twakeford]

Ok, that all makes sense. The editing of the component type was an addition I added during the mock-ups. It isn't high on the priority list and unlikely to have much demand, so to keep scope as narrow as we can, that function may get removed.

re

With the Review Files, if I remember correctly, these are attached to the email, but otherwise not visible in the author's submission dashboard.

I'm not getting any attached files when I select them during the decision process.

re

So my ideal approach here would be to have one checklist with only the files uploaded by reviewers. Then we can use an additional accordion toggle called "Share other files with the author" which would include two checklists, one with the Files for Review and one with Revisions (if they exist).

That sounds good - could we do that as a second attack at this workflow though? It sounds like that will add complexity to the process and keeping the scope as tight as we can would be beneficial (as there is one more large-ish contribution we want to work on pre-Sept)

[NateWr]

That sounds good - could we do that as a second attack at this workflow though?

Yeah, I think it will actually get done separately, but...

As the author will be provided with the full Review Files list anyway as part of the Revisions process, we should remove these files from the Editor decision workflow, so that they are only selecting whether to share the Reviewer files with the author.

...we can't just remove the full Review Files from the list. That's because we likely have journals that are making use of those files being there as part of their standard workflow. We at least need to know more about who is using them and why, and how they would need to adjust their workflows, before removing them.

[twakeford]

We at least need to know more about who is using them and why, and how they would need to adjust their workflows, before removing them.

Makes sense - can someone confirm whether they can see any functionality in the current list? If I tick one of the files uploaded by a reviewer, this does make it available to the author, but ticking any of the other files doesn't seem to do anything (i.e. no attachments, nothing obvious in the author Revisions page...). I may be missing something, but from what I can see the list seems to be offering files without a function = how to confirm this?

[NateWr]

@twakeford, I just did a test in stable-3_3_0 and I see files from all three sections getting attached to the email that is sent to the author. Here are the steps I took:

1. Upload a file to Review Files.
2. Upload a file to a Review Assignment (ie - from a Reviewer)
3. Upload a file to Revisions.
4. Click Accept Submission.
5. Select all three files to share with the author (the first step of the two-step process).

I used the mailLogger plugin to inspect the attachments and I see all three files were attached to the email:

    [attachments] => Array
        (
            [0] => Array
                (
                    [path] => /var/www/ojs/journals/1/articles/20/60ae133d93614.docx
                    [filename] => B-article-submission-final-version-proofread-v2.docx
                    [content-type] => application/vnd.openxmlformats-officedocument.wordprocessingml.document
                )

            [1] => Array
                (
                    [path] => /var/www/ojs/journals/1/articles/20/5fca339123faa.xls
                    [filename] => F-Full Sample 2020 Data Set - no filters.xls
                    [content-type] => application/vnd.ms-excel
                )

            [2] => Array
                (
                    [path] => /var/www/ojs/journals/1/articles/20/5ffda908d098b.html
                    [filename] => F-test.html
                    [content-type] => text/html
                )

        )

[NateWr]

Now that I think about it, I bet that the Review Files were made available in this list precisely because not all files were included in revisions! So I think with the new revision workflow, since all files will be in revisions, even if they were not revised, we'll no longer need to permit editors to attach Review Files to the decision email.

[twakeford]

That's what I'm thinking - if we're providing all the Review Files to the author anyway as part of the revisions process, then the editor won't need to select them individually at all....

[NateWr]

Yeah, you're right. Sorry that hadn't occurred to me. :+1: