User:NRodriguez (WMF)/Draft/Better diff handling of paragraph splits

Better diff handling of paragraph splits
Better diff handling of paragraph splits
	TBD
Group:	Community Tech
Team members:	Julieta Fernandez(Design), Harumi Monroy, MusikAnimal, Sam Wilson, Karolin Siebert
Lead:	Natalia Rodriguez (Product)
Updates:	Updates

This page contains changes which are not marked for translation.

Hello all, and thanks for coming to read more details about Better diff handling of paragraph splits. This was the #1 wish in the Community Wishlist Survey 2022. This article will outline our approach to addressing the user needs expressed in this Wish's proposal. We are asking for your feedback and insight so that we may make the best possible improvements.

Original Wish

Wish Objective Summary: Allow viewers to understand when paragraph spacing was inserted between two versions of a page.

Background & Problem Space

Wikidiff2 paragraph split

A diff, short for difference, displays the changes between two versions of a page.

The platforms in the wiki ecosystem have several versions of a Diff depending on which device and installation of Mediawiki is being used.

One way users can find an example of a diff is by navigating to the History of a given page and selecting two versions to compare.

On Desktop, there are two experiences available to most wikis:

WikiDiff2 is a native extension for PHP that provides a faster diff engine to MediaWiki. It is partly based on the original wikidiff, and partly on MediaWiki's DifferenceEngine class. It produces diffs from input text (line-based or word-level) and can format these as HTML or JSON. Wikidiff2 includes support for character-level diffs for text composed of characters.
Visual diff is currently a Beta Feature and compares and shows differences between rendered (or displayed) documents, as opposed to showing the text (or markup) that is used to format such documents.

On Mobile, there are three experiences:

In addition, users have also developed popular scripts to customize their diff experiences.

The number one wish on this year’s (2022) Community Wishlist Survey was Better diff handling of paragraph splits. This wish has appeared more than once on the different wishlists.

This wish called for an improvement on the diff viewer when a pargraph split is added - as it appears as deleted and re-added rather than just re-purposed.

Existing gaps: Product, Technical, and Design Debt

While researching this paragraph split issue, we discovered that other aspects of the diff viewer are unintuitive to the users (or at least for newcomers):

The use of color contrast is inaccessible in some platforms. Color should not be the only indicator of meaning, the use of strikes or other symbols should support the usage of color.
The two columns meant before (left) and after (right) with the symbols + and - in Wikidiff2 were unintuitive to some
People can associate "red" with bad and "green" with good which can lead to confusion about the quality of an edit
Line numbers are not shown in most of the platforms's editing experiences, but they do appear on diffs as the organizing unit
No parity between platforms

Why is it confusing to see a paragraph split?

The current Wikidiff2 experience organizes changes by line numbers.

This means that it will show an addition of a string or a character within a line as deleted and re-added. Since breaking up a paragraph means "adding a space bar character within a line and creating a new line" the current Wikidiff2 experience displays the content as deleted, and then the lines will be split into one that was re-added and another that was added. The line that is re-added will not highlight individual words that changed within the edit.

Scope of Work & User Stories

User Story requirements

As a visitor to the wikis, when I compare two versions of a page:

I want to clearly identify what was added so that I can understand what changed
I want to clearly identify what was deleted so that I can understand what changed
I want to clearly identify line break insertion so that I can understand what changed
I want to clearly identify changes to words within the lines that were split up, so that I can understand changed

Scope and Constraints

For the purpose of this improvement led by Community Tech, we will NOT be prioritizing UX improvements to the Diff:

Mobile web
IOS
Android improvements

While we may hold meetings with those teams and share knowledge about what our user research and technical investigations unveil, we will not be taking on the work of engineering the fixes to those platforms.

We will only be working on the core experience of comparing two versions of a page, this means that explicitly, there WILL not be design requirements around:

- Discoverability of the diff: We will not be focusing on how people navigate to the comparison of two revisions

- Other actions that users can take on the diff that are not related to comparison of changes

The above are all outside of the scope of what this team will focus on due to resourcing. We are aware of other internal efforts by the Moderator Tools team to address Mobile Web, and the IOS and Android teams owning those platforms respectively.

Data Investigations

Why and how did we accept this wish

This wish scored high in our prioritization process for 2022. It was very popular in terms of number of votes, impactful in terms of the benefit for the community, and had a relatively low complexity estimate. Diffs are a core piece of the wikis. Users need to understand what changed in a collaborative editing ecosystem.

Design Research

So far, we've ran some unmoderated user search to understand how intuitive our different "diff" experiences are. Please see the research protocol attached in the form a PDF together with the insights analysis in video form.

Usability Tests run on the Diff Experiences

Usability test analysis for Wikipedia's diff viewer

Visual diff scores:

4.5/5: content addition experience received an average ranking in terms of clarity.
4.5/5: content deletion experience received an average ranking in terms of clarity.
2.75/5: paragraph break experience received an average ranking in terms of clarity.

Wikitext2 diff scores:

4.75/5: content addition experience received an average ranking in terms of clarity.
4/5: content deletion experience received an average ranking in terms of clarity.
3.75/5: paragraph break experience received an average ranking in terms of clarity.

Status Updates

March 10, 2023

The team has continued work on this wish on both the engineering and design side and we wanted to share the updates with you.

Thank you to all of you who took the time to engage with us and provide feedback on the Talk page. We read through all of the feedback and did an aggregate analysis on the points made. We then combined your feedback on those proposed designs, as well as unmoderated user research, and we've finalized the proposed designs to go into engineering for the improvements regarding the wish changes. Please see the designs in this update which include:

Switching between diff modes via dropdown
Improving the accessibility of inline diffs with legends and tooltips for desktop
Improving the display of a change that introduced a new line or paragraph
Improving the display of a change that deleted an existing line or paragraph

In addition, demo of the changes for the underlying comparison engine has been created. Before you try out the demo to give us feedback, please note:

It's a work in progress, our QA engineers are currently using a list of comprehensive diffs to make sure the changes are consistent with the current version of the two-column diff experience or an improvement on the UI
The demo page does NOT include all final UI changes but can give testers a good sense of how the completed two-column diff experience will end up looking.
To use the demo, paste the same text into the two boxes and modify the text in the right box. The diff under it will show what changed.

We'd love to hear your feedback on our Talk Page!

Next Steps

Accessibility of Design Colors: Our designer is working closely with our Design Systems team to determine the accessibility of the designs. We anticipate having to change the shade of them to a slight degree to make it more accessible but the colors will remain similar to the blue and yellow currently displayed on two-column and inline diffs.

Release plan: We are working out a release plan and a timeline of next steps and will be including this in our next project updates! Releasing changes to the underlying engine on the diff follows a different process than traditional releases in Mediawiki software so we will be sure to update you with steps and details next time.

We also want to include big thank you in this update to a non-Community Tech staff member, Tim Starling, who graciously stepped up to help us with the underlying changes in the C++ engine of wikidiff2. We are always happy to receive support fulfilling wishes from other members at the Foundation that have the expertise necessary to fulfill a wish even if they are not in the Community Tech team.

We're looking forward to hearing from all of you

Open Questions: We want to hear from you!

Are you interested in conducing user research on the new proposed interface to diff paragraph splits? If so, will you please post that you're interested in the Talk Page?
What other pain points manifest themselves when you view the diff?
How might we address the root pain points that address the confusion around paragraph splits?
How does the use of color indicate what is