Page MenuHomePhabricator

Wikisource: Improve support for users that experience ebook export errors
Closed, ResolvedPublic3 Estimated Story Points

Description

As a Wikisource user, I want to see helpful messaging when I experience ebook errors that tells me 1) that there is an error, and 2) what I can do about it, so that I can successfully download a book or pursue relevant next steps.

Background: This is a follow-up to the T274575. Through this work, we determined that we wanted to implement a light-weight solution directly on the Wikisource Export page, so that users who experience download errors can receive helpful messaging about the error & next steps. For more background, please refer to T274575.

Relevant Resources:

Acceptance Criteria:

  • When a request for an ebook export results in an error for a user, the user should:
    • Be redirected to the Wikisource Export page (if they are not there already)
    • Display "Download failed. Learn more." as default message in the error header
    • Current colors & general design for error header can remain
    • If possible, display a customized error message based on the error type that is experienced by the user
      • Note: This is TBD based on discussion with engineers on how much information we can share based on specific error vs. a more generalized message to cover all cases. This may also be explored in a separate ticket.
    • If the user clicks on the "Learn more" link, the error header will expand & provide recommendations on how to download the book again, which will be written as follows:
      • Please try these steps if you encounter an error:
      • 1. Try to download the book again.
      • 2. Try to download the book as an EPUB file.
      • 3. Check the box in "Options" to remove credits.
      • 4. Check the box in "Options" to remove images.
  • The error message can be closed via the "x" icon at the top left of the error header
  • If possible, this should apply to all download errors, but preference would be for errors that are encountered via Download button, if we can't cover all cases within a reasonable scope

Visual Examples:
Example of what user initially sees upon experiencing an ebook export error


Example of what user initially sees if they click on "Learn more"

Event Timeline

Restricted Application added a subscriber: Aklapper. ยท View Herald TranscriptMar 11 2021, 9:40 PM
ifried renamed this task from Wikisource: to Wikisource: Improve support for users that experience ebook export errors.Mar 11 2021, 9:42 PM
ifried updated the task description. (Show Details)
ifried updated the task description. (Show Details)
ifried updated the task description. (Show Details)
ifried updated the task description. (Show Details)
ifried updated the task description. (Show Details)
ifried updated the task description. (Show Details)
ifried set the point value for this task to 3.Mar 12 2021, 12:27 AM
ifried moved this task from To Be Estimated/Discussed to Estimated on the Community-Tech board.

The error message can be closed via the "x" icon at the top left of the error header

@nayoub The Bootstrap standard is for it to be at the top right. Is that okay? Like this:

@Samwilson Yes that works great โ€“ it is standard for the close icon to be on the top right. The other 'x' icon on the left was representing an 'error icon', that's why it was bigger and bolder than the 'x' for close on the right.

Thanks @nayoub

I've added the 'learn more' link as a button (for better accessibility and correct semantics), which with Bootstrap 3 means it's not aligning quite correctly. This seems to be a tricky thing to solve across browsers, and I suspect we're going to do more overhauling of the whole UI in T277239 so perhaps it can be fixed then (e.g. by using a more modern Bootstrap version). Does that sound okay?

PR ready for review: https://github.com/wikimedia/ws-export/pull/343

dom_walden added a subscriber: dom_walden.

For "predictable errors", the error message now looks like:

These predictable errors include things like:

  • User enters an ebook that does not exist
  • User enters an invalid language
  • User enters an invalid format
  • If possible, this should apply to all download errors, but preference would be for errors that are encountered via Download button, if we can't cover all cases within a reasonable scope

We currently show something different for 500 errors compared to the more predictable errors. It does not have the custom error message, "back to wikisource", etc.

For example, for a timeout error:

@nayoub @ifried I am wondering if the custom message wouldn't actually be more useful for these unpredictable 500 errors (if this is something we can do technically). These errors are more likely to be caused by things like the export timing out or the server being under load, which the suggestions in the custom message might help.

The predictable errors already have error messages tailored for their particular failure condition. I don't think any of the the suggestions in the custom message are likely to help in the case of predictable errors and may be unnecessary.

E.g., when entering an invalid format:

Predictable error messages include:

  • For non-existent book or invalid language: The book 'foo' could not be found.
  • For invalid format: "blah" is not a valid format. Valid formats are: "epub-3", "epub-2", "htmlz", "mobi", "pdf-a4", "pdf-a5", "pdf-a6", "pdf-letter", "rtf", "txt"
  • For an API error (e.g. could not get data from parsoid): Unable to retrieve URL: <url>

Test environment: https://ws-export-test.wmcloud.org version 2.4.1-11-gb284e56.

Yes, I agree @dom_walden, I think it would be helpful for the users to also have custom messages on unpredictable 500 errors.
It would also add consistency with the predictable errors. Maybe we could display a message along those lines:

An error occurred. *Learn more*

Your download failed because of a server error. Please try these steps:

  1. Try to download the book again.
  2. Try to download the book as an EPUB file.
  3. Check the box in "Options" to remove credits.
  4. Check the box in "Options" to remove images.

If the error persists, please report an issue on Phabricator.

What do you think @ifried ?

This makes sense & I agree, @dom_walden & @nayoub. It would be helpful to users who encounter 500 errors to receive a message with guided next steps, just like users receive when predictable errors occur.

One small nit-pick: I would maybe just replace "because of a server error" with "due to a server error," since it's a bit shorter/simpler. Otherwise, the language provided in the above comment sounds great.

My one concern is the timeline: Ideally, we want this project to be wrapped up by the end of the month, so we can focus on the OCR Improvements project. I'll reach out to the team and see if we have time/capacity to work on this soon (hopefully we can!).

This is now on production, and I'm marking it as Done.