Page MenuHomePhabricator

Consider clarifying the visual language for Visual Diffs
Open, NormalPublic8 Story Points

Description

Based on the analysis that @Prtksxna, I captured some ideas about the following points (illustrated with a mockup below):

  • Show formatting and link changes as side notes. This can help to avoid content edits become too verbose. That is, tell the user that a link was added instead of showing a word deleted, the same word with a link, and let the user figure out what changed. This helps to focus the red/green comparisons for content changes, while style and other information is captured at the side. In the examples I used a different color (yellow) to signal those annotations.
  • Make it clearer how the paragraphs were moved. The current triangles are not obvious to understand where a paragraph was removed from and added to. In the example, I used the stroked text to show the place where content was (stroked but not in red since the content has not disappeared completely from the document) and green to show where it has been inserted. side annotations help to connect the dots: hovering will highlight both, an clicking on one may scroll to the other (in which case we may make arrows in blue to convey interactivity). Intermediate paragraphs that just move up because another paragraph was moved, are not signaled.

Event Timeline

Restricted Application added a project: VisualEditor. · View Herald TranscriptJun 30 2017, 12:09 PM
Restricted Application added a subscriber: Aklapper. · View Herald Transcript

@Pginer-WMF Minor note: It seems like you've used Base50 for the arrows(?), I'd pledge for using Base30 for minimum contrast reasons.

Schnark added a subscriber: Schnark.Jul 1 2017, 7:57 AM
Pginer-WMF updated the task description. (Show Details)Jul 3 2017, 9:01 AM

@Pginer-WMF Minor note: It seems like you've used Base50 for the arrows(?), I'd pledge for using Base30 for minimum contrast reasons.

Thanks @Volker_E. I updated the mockup to increase the contrast of the arrows.

Show formatting and link changes as side notes

We decided against showing changes that are visually clear as a remove/insert as side notes for the time being for a few reasons:

  • While cleaner in the document, can lead to too much clutter in sidebar
  • Inconsistent with new text which has been annotated, which wouldn't get a sidebar indicator.
  • Requires extensive i18n work, probably multiple messages per annotation (and there are quite a few annotations + plus extensions could add annotations)

I think there are good arguments on both sides, but think we should get some more feedback before committing to a fairly large piece of work.

Using the sidebar for paragraph moves is an interesting idea and we need to file a separate bug for the excess moves we are showing that needs to be resolved first.

Show formatting and link changes as side notes

We decided against showing changes that are visually clear as a remove/insert as side notes for the time being for a few reasons:

  • While cleaner in the document, can lead to too much clutter in sidebar
  • Requires extensive i18n work, probably multiple messages per annotation (and there are quite a few annotations + plus extensions could add annotations)

I think there are good arguments on both sides, but think we should get some more feedback before committing to a fairly large piece of work.

One minor issue with the move as you have it designed, is that part of the point of the move feature is that we can show changes within a moved paragraph (a big improvement on the current differ), so painting the whole thing green wouldn't work.

Pginer-WMF updated the task description. (Show Details)Jul 11 2017, 9:40 AM
Pginer-WMF added a subscriber: dchen.

Show formatting and link changes as side notes

I think there are good arguments on both sides, but think we should get some more feedback before committing to a fairly large piece of work.

I totally agree. I think that Visual Diffs allows us to easily recreate some individual examples of realistic diffs with mockups and place them in front of users to get feedback. I'd definitely recommend doing such exercise before investing time in the code to support possible directions. @dchen can provide more thoughts and ideas for such process.

One minor issue with the move as you have it designed, is that part of the point of the move feature is that we can show changes within a moved paragraph (a big improvement on the current differ), so painting the whole thing green wouldn't work.

Makes sense. I think the approach can be tweaked to reflect changes inside a moved paragraph (I updated the mockup in the description with one possible approach). The main goal I tried to capture was to make the paragraph move more explicit, which I think the current triangles by themselves do not support perfectly well (especially thinking in the scenario of reviewing other people's changes where you lack the context of what was done while editing).

One minor issue with the move as you have it designed, is that part of the point of the move feature is that we can show changes within a moved paragraph (a big improvement on the current differ), so painting the whole thing green wouldn't work.

FYI: WMDE's technical wishes team is in the final stages of implementing just this in the current differ (i.e.wikidiff2): T139603: Show text changes when moving text chunks (#2)

One minor issue with the move as you have it designed, is that part of the point of the move feature is that we can show changes within a moved paragraph (a big improvement on the current differ), so painting the whole thing green wouldn't work.

FYI: WMDE's technical wishes team is in the final stages of implementing just this in the current differ (i.e.wikidiff2): T139603: Show text changes when moving text chunks (#2)

Awesome! Could you share some screenshots? The links to https://mwdiffstuff.wmflabs.org/ aren't working

cmadeo added a subscriber: cmadeo.Jul 18 2017, 5:22 PM
Deskana triaged this task as Normal priority.Jul 18 2017, 7:28 PM
Deskana moved this task from To Triage to TR6: Visual diffs on the VisualEditor board.

…I updated the mockup in the description with one possible approach…

I was thinking of a few more ways to do this which don't require a gray background:

Using the sidebar for paragraph moves is an interesting idea and we need to file a separate bug for the excess moves we are showing that needs to be resolved first.

T171451: Stop showing excessive moves when moving a paragraph across the page

  • Requires extensive i18n work, probably multiple messages per annotation (and there are quite a few annotations + plus extensions could add annotations)

Is the extra i18n work about having a ton of new messages, or is it more complicated than that?

I'm not sure the moved content should be shown twice in its entirety - it could make the diff quite complicated in cases where multiple paragraphs or whole sections are moved, or where multiple moves are made...

I'm not sure the moved content should be shown twice in its entirety - it could make the diff quite complicated in cases where multiple paragraphs or whole sections are moved, or where multiple moves are made...

Makes sense. We can do some clipping in the "removed" paragraph. Possible in the "moved" one too, if there are no changes?

…I updated the mockup in the description with one possible approach…

I was thinking of a few more ways to do this which don't require a gray background:

My concern with these approaches is that while you can figure out the changes if you already know a paragraph was moved, that information is hard to extract if you don't have it already. In the 1st and 3rd approach arrows point to an area with content in between which adds confusion.

The 2nd approach makes use of an independent vertical scan line, which is good in my opinion. However, the opposing arrows are not communicating that the paragraph was moved from point A and landed in point B. Notice in my example above that the destination arrow points to the place content was inserted so you can actually follow the arrows to reach to the content.

I'm not sure the moved content should be shown twice in its entirety - it could make the diff quite complicated in cases where multiple paragraphs or whole sections are moved, or where multiple moves are made...

That's something to consider. Keeping a limit in the number of lines to show on the removed content as indicated by @Prtksxna could be a reasonable approach if leaving a more explicit trace of the moved paragraph helps to clarify what happened. Please, feel free to share any diff you consider representative of this case, and we can try to apply different approaches to evaluate them.

dchen added a comment.Jul 27 2017, 6:17 AM

I wonder what other ways there may be to address @Tchanders concern about multiple moves involving paragraphs/sections.

I will however +1 Pau's approach above. Even with multiple moves, the highlighting of origin and destination locations of the moved paragraph/section and the comments with indicator arrows (moved down, moved from above) offers clarity. Can imagine that this format would hold even with multiple moves. Re Prateek's 3 mockups; with highlighting on hover, I could see these being good options, but highlight tying the two blocks/showing directionality would be more of a necessity than a nice-to-have. As Pau mentioned, it's difficult to tell at quick glance what's happened: 1 & 2, especially if other edits exist between, look to me that perhaps one paragraph is moved down and another is moved up. 3 could potentially be misconstrued as both paragraphs are moved down.

However that's just my opinion. I'm game to throw these and other additional mockups and/or prototypes into user testing for feedback.

I'm wondering whether it is really necessary that the diff tells you exactly where each of the paragraphs moved.
Of course, one could create a diff view that tells you exactly: "The first paragraph was moved 3 places down, the second 1 up, the third stayed in its place (except that no 1 moved past it), and ..."
Does this really add clarity over a diff view that tells you: "The paragraphs were heavily re-ordered, but except this minor typo correction shown in red and green, no other changes to the text occurred. If you want to see and compare the order of the paragraphs before and after the edit, please look at the old and new version."
I'm not saying that there is no point in showing the user which moves happened, but for simple moves it should be easy to understand for any reasonable presentation, while for complicated moves it will be hard in any presentation of the diff.

I'm wondering whether it is really necessary that the diff tells you exactly where each of the paragraphs moved.

That's a valid point. I was proposing to mark more clearly A and B as a way to communicate the movement, since just the triangles require a lot of interpretation.
But my main concern was with the triangles not representing such movement. I created some examples based on a very basic case where paragraphs just switched positions, to compare the current approach with more implicit and explicit options to communicate the movement:

Blue triangles

Explicit movement with annotations and preserving part of the original paragraph

Note that in this case you only need to illustrate the movement of one of the paragraphs to get the whole picture. I decided to illustrate the top paragraph going down, but the algorithm could pick to do so with the bottom paragraph going up. In any case, only one should be represented to avoid crowding the diff unnecessarily.

Arrows representing the trajectory

The arrows bring both meanings: the paragraph was moved from above/below and was inserted in the current position.

Note also that paragraphs aren't the only things that can be moved: tables. headings, images (including floating images) need to be marked in the same way.

Tchanders added a comment.EditedJul 31 2017, 2:02 AM

In T169325#3477128, @Schnark wrote:
I'm wondering whether it is really necessary that the diff tells you exactly where each of the paragraphs moved.

I'm wondering the same thing. I agree that it's nice to know exactly what happened for a simple move, but that for anything more complicated it's probably more useful just to be aware that some moves have happened.

If we treat simple and complicated moves differently, then we'll have the problem of defining simple vs. complicated, so it might be easier to find a solution that would work for both. How about highlighting whether the moved item has moved up or down, but without displaying where it came from? In some cases, where the moved item came from won't even be clearly defined. E.g. here "one" and "four" are swapped:

Did "one" originate from above where "four" is now, or just below it? Same question for "four"? @Pginer-WMF I think this is an example of a relatively simple move where seeing where the paragraphs came from could be more confusing. @dchen As to how common moves like this (and more complicated moves) are, I suppose there's a way to research that?

I like that in @Pginer-WMF's second and third examples only one paragraph is marked as moved. Currently (as in the first example) too many moves are displayed. For more complicated examples, a minimal move diff should be computed.

In T169325#3477128, @Schnark wrote:
I'm wondering whether it is really necessary that the diff tells you exactly where each of the paragraphs moved.

I'm wondering the same thing. I agree that it's nice to know exactly what happened for a simple move, but that for anything more complicated it's probably more useful just to be aware that some moves have happened.

Another thing to consider is that we don't need to show all information statically. It is also possible to provide part of the information initially and show more details as users hover/click/select a specific part of the diff to get more details.

If we treat simple and complicated moves differently, then we'll have the problem of defining simple vs. complicated, so it might be easier to find a solution that would work for both.

Agree. A single approach seems the right way to go. Ideally an approach that works really well for the most common cases and well enough for the edge ones (and collecting those examples would be help to design and test the approach).

How about highlighting whether the moved item has moved up or down, but without displaying where it came from?

Makes sense. As I saw in the example below, explicitly indicating the origin of a move can crowd the diff when those moves occur in a reduced space. However, I think that the triangles alone are not communicating well that a paragraph moved.

In some cases, where the moved item came from won't even be clearly defined. E.g. here "one" and "four" are swapped:


Did "one" originate from above where "four" is now, or just below it? Same question for "four"? @Pginer-WMF I think this is an example of a relatively simple move where seeing where the paragraphs came from could be more confusing.

You are right. Showing the origin point on this example (approach C below) makes the diff too crowded. Clarifying things on hover could help, but we probably want the approach to be more clear from the very beginning.

I illustrated different approaches below:

ABC
Deskana set the point value for this task to 8.Aug 22 2017, 2:21 PM

How about highlighting whether the moved item has moved up or down, but without displaying where it came from?

I like that in @Pginer-WMF's second and third examples only one paragraph is marked as moved. Currently (as in the first example) too many moves are displayed. For more complicated examples, a minimal move diff should be computed.

Note also that paragraphs aren't the only things that can be moved: tables. headings, images (including floating images) need to be marked in the same way.

How about we show only an indicator of what has moved? The move marker could have some metadata and possibly an excerpt:

Not yet sure if its a good idea but the convention could be to have green for additions, red for deletions, yellow for formatting/link changes, and blue for moves. The move markers could also be links that scroll you to the position of where the object have moved. A few more examples:

This could be applied to references too.

I think I'd still be concerned about crowding the diff if the origin is highlighted, even if only a small excerpt is shown (see @Pginer-WMF's example C above)... But maybe we'd have to balance how common/bad this would be compared to how much there is to gain from knowing exactly where the origin was.

I very much like being clearer about whether content was moved up or down, using the arrows and text.

I also like the idea of different colours for additions, deletions, format/data changes and moves. In particular I think the current situation with format/data changes looking the same as additions and deletions is far from ideal, and also relatively simple to correct technically.

Volker_E added a comment.EditedSep 6 2017, 1:59 AM

Agree with @Tchanders of option C above being too crowded.

@Prtksxna Links could be an interesting idea, but is the need for knowing where something has moved worth the coding effort? Does it really provide a solution to a strong enough user need?

Also, please consider color coding not to be the only way to provide information.

@Prtksxna Links could be an interesting idea, but is the need for knowing where something has moved worth the coding effort? Does it really provide a strong enough user need?

Will need testing for that. I think it'll prove to be more useful while looking at the History and trying to understand someone else's changes (not your own during Preview changes).

Also, please consider color coding not to be the only way to provide information.

This doesn't rely solely on color. The text says clearly that its a move, the shape too is unlike any other in the diff, what improvements would you suggest?

Also, please consider color coding not to be the only way to provide information.

This doesn't rely solely on color. The text says clearly that its a move, the shape too is unlike any other in the diff, what improvements would you suggest?

Delete has in all image examples strike-through applied. “Bold style applied“, “Link added” and inserted text has just different (background-)color added, which could easily fail for certain visually impaired users. Referring mostly to the image in description.

Prtksxna added a comment.EditedSep 20 2017, 8:44 AM

Delete has in all image examples strike-through applied. “Bold style applied“, “Link added” and inserted text has just different (background-)color added, which could easily fail for certain visually impaired users. Referring mostly to the image in description.

I think I am misunderstanding your comment. Are you talking about the image in the description of the task? I was currently only talking about the mockup that I uploaded in my last comment: https://phabricator.wikimedia.org/T169325#3576399

@Prtksxna The part about color to convey change was a general comment, in the examples given referring to the task description image.

@Prtksxna The part about color to convey change was a general comment, in the examples given referring to the task description image.

In the image in the description, the deleted text is both red and has a strike-through, the moved paragraph is gray, has a strike-through, and an annotation in the sidebar.

The additions are just green, and the formatting changes are yellow and an annotation in the sidebar. These two could be confused, yeah. Do you have any suggestions? Maybe use just an outline for the formatting change? That usually visually clutters the text. @Volker_E what would you suggest?

@Prtksxna An quick idea that comes to my mind is dotted underline.

marcella added a subscriber: iamjessklein.