Community Wishlist Survey 2022/Better diff handling of paragraph splits

Better diff handling of paragraph splits
Better diff handling of paragraph splits
	Improve MediaWiki diff display for paragraphs that are split and modified.
Group:	Community Tech
Team members:	Tim Starling, Joydeep Sengupta, Dayllan Maza, Harumi Monroy, MusikAnimal, Sam Wilson, Karolin Siebert, Sandister Tei, Sammy Tarling
Lead:	Joydeep Sengupta, Dayllan Maza and Karolin Siebert (Product Owners)
Updates:	Updates

Translate this page

Better diff handling of paragraph splits was the #1 wish in the Community Wishlist Survey 2022. The objective of the wish is to allow viewers to understand when paragraph spacing was inserted between two versions of a page. This page outlines Community Tech's approach to addressing the needs expressed in this wish's proposal. Please leave feedback if you have any.

This page documents a project the Wikimedia Foundation's Community Tech team has worked on or declined in the past. Technical work on this project is complete.

We invite you to join the discussion on the talk page.

See original Wish

Background & Problem Space

Wikidiff2paragraph 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. Wikidiff2includes 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 paragraphs that were split up, so that I can understand what changed

MVP Requirements

As a viewer of the Two-column Wikitext Diff diff on Desktop

I am able to see a visual marker to show when a word changed within a paragraph that was split up as its own paragraph

As a screen reader user of the diff,

I am able to access accurate and helpful descriptions about the changes of the deletion and addition columns, as well as the visual descriptors of what changed

Ideal Scope Requirements

As a viewer of the Wikitext diffs on Desktop,

I will be able to choose between viewing a unified inline or two-column diff

As a viewer of the Unified Inline Wikitext Diff diff on Desktop,

I am able to see a visual marker over removed text
I am able to see a visual marker to show when a word changed within a paragraph that was split up as its own paragraph
I am able to see a visual marker to show the addition of new lines
I will be able to see a legend so that I can understand what visual markers mean

Scope and Constraints

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

Mobile web
iOS
Android
VisualDiff

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.

Design debt and plans:

Are we going to match the style Visual Diff to match the ones in the Wikitext diffs?

Depending on complexity, likely yes.

Are we going to match the style Mobile Web Diff to match the ones in the Wikitext diffs?

We will share our research and final mocks in real time with the Moderator Tools team currently touching that experience

Data Investigations

How many users visit the two-column diff pages?
How many users visit the inline diff page?

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.

Status Updates

September 29, 2023

Close to the end of September 2023, iterative Better Diff updates listed below have been released. The changes apply to wikis where Wikidiff2 is installed.

Roll out of inline switch widget

The new inline toggle switch widget in diff pages has been rolled out by Community Tech.

The inline toggle switch allows viewers to toggle between viewing wikitext diffs as a two-column diff or as a unified inline diff.

Inline toggle switch

Paragraph split detection

The paragraph split detection in Wikidiff2 has been deployed to all wikis. Overall accuracy of paragraph split detection has been improved.

The system better identifies where new lines were added and deleted. We are currently awaiting user feedback for reports of inaccurate diffs so we can adjust the algorithm to get better results.

We addressed issues identified in the Better Diff wish and also mentioned on Phabricator, hence paragraph splits and moves should now be identified properly in diffs.

Adding a legend and tooltips

Better Diff project has also introduced legends and tooltips to inline diff so that users seeing the blue and yellow highlights, which depict changes, can better understand the type of edits made.

In Wikitext two-column diff view, individual words changed inside a paragraph that has been split, isn’t highlighted or noted anywhere. This could cause users to miss vandalism. However in inline diff mode, the content added is highlighted blue, and content removed is highlighted yellow.

Once the switch is toggled on, a legend on the top left of the diff page indicates that edits highlighted blue represent content added and edits highlighted yellow are content deleted.

Additionally, when users hover their cursors over a highlighted section, a tooltip appears to inform them which kind of edit (and addition or removal) was made.

Better Diff legend and tooltip

Adding and deleting lines

If a user inserts one or more lines, it is represented with the text "newline" highlighted in blue. Deleting one or more lines will be represented with the text "deleted" in a yellow highlight.

Adding and deleting new lines in Better Diff

April 14, 2023

Community Tech has some upcoming releases regarding Better Diffs in the coming months. The releases will cover improvements to the Wikidiff2 algorithm and better diff user interface (UI) enhancements.

The Wikidiff2 algorithm will be able to capture paragraph splits better and identify changes to words within the paragraphs that were split.

The UI enhancements will contain upgrades to the inline format and a format switcher. The inline format will show legends and tooltips so that users can better understand edits.

The switcher will allow users to easily navigate the different possible formats, including inline, two columns, and visual.

The table below tracks the releases on Phabricator.


#	Task	Code (Core, VE, Wikidiff2)	Release dates
1	Inline Diff: Add legend and tooltips	Core	Week of July 3
2	Better Diffs: Wikidiff2 revise algorithm	Wikidiff2	Week of July 17
3	Inline diff: one or more lines added or deleted	Core and Wikidiff2	Week of July 17
4	Better Diffs: Complete deployment of Wikidiff2 improved split detection to all wikis	Core	Week of August 30
5	Inline Switch: Add inline format toggle when wikidiff2 is installed	Core and VE	Week of September 11

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.

Visual diff

Wikitext – inline

Wikitext – two columns

Review changes – two column

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, a 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 from first update: 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 which content is added, removed, or stayed the same?