Difference between revisions of "User:Prtksxna/VeDiff"

From MediaWiki.org
Jump to navigation Jump to search
Line 1: Line 1:
 
{{Note|Please edit this page directly with new points or comments (don't use the talk page)|reminder}}
 
{{Note|Please edit this page directly with new points or comments (don't use the talk page)|reminder}}
   
This document looks at the new visual diffs at different levels.
+
This document looks at the new visual diffs at different levels:
 
* Very specific, like particular kinds of diffs that are hard to figure out.
 
* Very specific, like particular kinds of diffs that are hard to figure out.
 
* General comments on how the diffs are shown with some specific examples.
 
* General comments on how the diffs are shown with some specific examples.
 
* High level, about the idea and scope of this feature.
 
* High level, about the idea and scope of this feature.
Everything here could be on Phabricator, but I wasn't sure what should and should not. Some of the things here might already be {{Done}}, {{In progress}}, or tracked. Feel free to add necessary templates, like [[Template:Tracked]] to the relevant subheadings. The document doesn't offer alternative designs (only suggestions), if we do feel that something needs design work, we'll track and move that to Phabricator.
+
Everything here could be on Phabricator, but I wasn't sure what should or should not. Some of the things here might already be {{Done}}, {{In progress}}, or tracked. Feel free to add [[Template:Tracked]] to relevant subheadings. The document doesn't offer alternative designs (only suggestions), if we do feel that something needs design work, we'll track and move that to Phabricator.
   
 
== Scope ==
 
== Scope ==
Is it a diff of all the visual changes of the page, or a visual way to see the diff of all the changes that have occurred in the page?Is the scope of this feature to also surface ''hidden'' changes like those to the metadata of the page or adding a comment to the page?
+
Is it a diff of all the visual changes on the page, or a visual way to see the diff of all the changes that have occurred on the page? Is the scope of this feature to also surface ''hidden'' changes like those to the metadata of the page or adding a comment?
   
 
The changes are currently being shown in two ways, the red and green diffs, or as a comment in the sidebar. There usually is a blue highlight in the diff that corresponds to a comment in the sidebar. How are we deciding which changes need to be shown in which way? The way I see it, it can be reasoned about in two ways:
 
The changes are currently being shown in two ways, the red and green diffs, or as a comment in the sidebar. There usually is a blue highlight in the diff that corresponds to a comment in the sidebar. How are we deciding which changes need to be shown in which way? The way I see it, it can be reasoned about in two ways:
Line 21: Line 21:
 
How effectively can someone…
 
How effectively can someone…
 
* trying to find a particular change spot it in the diff?
 
* trying to find a particular change spot it in the diff?
* not actively looking spot the change (for eg, a mistake)?
+
* not actively looking be able to spot the change (for eg, a mistake)?
 
How effectively does the diff...
 
How effectively does the diff...
 
* communicate what has changed?
 
* communicate what has changed?
Line 31: Line 31:
   
 
==== Accessibility ====
 
==== Accessibility ====
Color alone should not be an indicator for information. Certain critical changes that are small should be loud.
+
Color alone should not be an indicator for information? Certain critical changes that are small should be loud?
   
 
We'd usually increase effectiveness, decrease noise and maintain accessibility. But, there could be exceptions, those should be discussed and noted.
 
We'd usually increase effectiveness, decrease noise and maintain accessibility. But, there could be exceptions, those should be discussed and noted.
Line 60: Line 60:
   
 
=== Contrast of surrounding context text ===
 
=== Contrast of surrounding context text ===
The context text surrounding the actual change is black and at 40% opacity. Thus, the resulting color is about <code>#989898</code> which has a contrast ratio of '''2.88:1''' against the white background. This does not pass the [http://webaim.org/resources/contrastchecker/ WCAG AA or AAA] standard. Bumping up the opacity to 60%, making the color <code>#656565</code>, has a contrast ratio of '''5.83:1''' which passes WCAG AA.
+
The context text surrounding the actual change is black and at 40% opacity. The resulting color is about <code>#989898</code> which has a contrast ratio of '''2.88:1''' against the white background. This does not pass the [http://webaim.org/resources/contrastchecker/ WCAG AA or AAA] standard. Bumping up the opacity to 60%, makes the color <code>#656565</code>, which has a contrast ratio of '''5.83:1'''. This passes WCAG AA.
 
[[File:Ellipsis on top .png|thumb]]
 
[[File:Ellipsis on top .png|thumb]]
   
Line 71: Line 71:
 
The vertical ellipsis can be a bit confusing:
 
The vertical ellipsis can be a bit confusing:
 
* They don't offer any interaction or information.
 
* They don't offer any interaction or information.
* The hover surface is limited and doesn't give context.
+
* The hover surface is small and doesn't give any information.
 
We could:
 
We could:
 
* Add hover text that tells how many lines/paragraphs have been skipped in between.
 
* Add hover text that tells how many lines/paragraphs have been skipped in between.
Line 85: Line 85:
 
|[[File:Move-para-2-up.png|frameless|400x400px]]
 
|[[File:Move-para-2-up.png|frameless|400x400px]]
 
|}
 
|}
It is hard to decipher visually if the chevrons are associated with the paragraph they're next to, the line they're next to, or are different entity altogether. In the first example, on the first look, the two arrows resemble a scroll bar, and hovering over the arrows doesn't give you any information either. When a paragraph is moved a large distance, every paragraph in between carries the arrow redundantly and there is no context clipping.
+
It is hard to decipher visually if the chevrons are associated with the paragraph they are next to, the line they are next to, or are a different entity altogether. In the first example, at first glance, the two arrows resemble a scroll bar, and hovering over the arrows doesn't give you any information. When a paragraph is moved a large distance, every paragraph in between carries the arrow redundantly and there is no context clipping.
   
 
== Confusing diffs ==
 
== Confusing diffs ==

Revision as of 05:24, 24 June 2017

Please edit this page directly with new points or comments (don't use the talk page)

This document looks at the new visual diffs at different levels:

  • Very specific, like particular kinds of diffs that are hard to figure out.
  • General comments on how the diffs are shown with some specific examples.
  • High level, about the idea and scope of this feature.

Everything here could be on Phabricator, but I wasn't sure what should or should not. Some of the things here might already be Yes Done, In progress In progress, or tracked. Feel free to add Template:Tracked to relevant subheadings. The document doesn't offer alternative designs (only suggestions), if we do feel that something needs design work, we'll track and move that to Phabricator.

Scope

Is it a diff of all the visual changes on the page, or a visual way to see the diff of all the changes that have occurred on the page? Is the scope of this feature to also surface hidden changes like those to the metadata of the page or adding a comment?

The changes are currently being shown in two ways, the red and green diffs, or as a comment in the sidebar. There usually is a blue highlight in the diff that corresponds to a comment in the sidebar. How are we deciding which changes need to be shown in which way? The way I see it, it can be reasoned about in two ways:

  • Visual change should be shown in the red/green way. This would mean that formatting changes, and converting some text to a link would show up in the diff.
  • Text change should be shown in the red/green way. This would mean that formatting changes, and converting some text to link would not show up in the diff, and in the comment sidebar instead.

Picking an approach would depend on what a majority of users expect from it. We should be consistent about it either way.

Scales

Different kinds of diffs can be rated at several scales. These can be used to reason about, and compare design solutions.

Effectiveness

How effectively can someone…

  • trying to find a particular change spot it in the diff?
  • not actively looking be able to spot the change (for eg, a mistake)?

How effectively does the diff...

  • communicate what has changed?
  • provide the context to understand the change?
  • bring attention to itself?

Signal vs. Noise

While the visual diff is already a huge step in reducing noise, we should be wary about new kinds of noise that could surface. One could decide to hide certain information, show it when asked for, or on certain interactions, or show it all the time.

Accessibility

Color alone should not be an indicator for information? Certain critical changes that are small should be loud?

We'd usually increase effectiveness, decrease noise and maintain accessibility. But, there could be exceptions, those should be discussed and noted.

Showing the changes

Adding a link as a meta change

Adding a link to some existing text could be shown in the 'comments' instead of in the diff.

Simple formatting changes

Simple formatting changes like bold or italicized could be shown in the 'comments' instead of in the diff.

Yes Done Link comments with the change in the diff

Sometimes it is hard to figure out what the comment is about. Like comments in Google Docs, it should be possible to select it and see what part of the document it is referring to.

Remove strike-through on hover

Will improve readability.

Hover-strikethrough.gif

Showing comments

Currently a new comment shows up as an added space in the content. Should this be complemented with a 'comment'?

Add-comment-visual-diff.png

<del> for paragraphs?

Is it possible to add the <del> tag inside paragraphs that are <p data-diff-action="remove">? This would make the interface consistent with simple word removals and more accessible.

Contrast of surrounding context text

The context text surrounding the actual change is black and at 40% opacity. The resulting color is about #989898 which has a contrast ratio of 2.88:1 against the white background. This does not pass the WCAG AA or AAA standard. Bumping up the opacity to 60%, makes the color #656565, which has a contrast ratio of 5.83:1. This passes WCAG AA.

Ellipsis on top .png

Vertical ellipsis

Templates on top

When there are templates on the top of the page, and the lead section of the article is edited, it adds a vertical ellipsis on the top which is confusing. This is one of the things that need to be discussed as part of scope, should we show the ellipsis for non-visual content?

Functionality

The vertical ellipsis can be a bit confusing:

  • They don't offer any interaction or information.
  • The hover surface is small and doesn't give any information.

We could:

  • Add hover text that tells how many lines/paragraphs have been skipped in between.
  • Add gerrit like functionality that lets you see more context where needed.Gerrit-diff-context.png

Moving paragraphs

The diffs produced when moving paragraphs and making some changes to the moved paragraph are great. It doesn't add the noise of completely removing and adding new lines. The representation, however, is unclear.

Move paragraph up once Move paragraph up twice
Move-para-1-up.png Move-para-2-up.png

It is hard to decipher visually if the chevrons are associated with the paragraph they are next to, the line they are next to, or are a different entity altogether. In the first example, at first glance, the two arrows resemble a scroll bar, and hovering over the arrows doesn't give you any information. When a paragraph is moved a large distance, every paragraph in between carries the arrow redundantly and there is no context clipping.

Confusing diffs

Removing a space

Removing a space is shown as a space with a red background and strike-through. This looks the same as removing a hyphen.

Visual Wikitext
Remove space
Remove-space-vediff.png
Remove-space-diff.png
Remove hyphen
Remove-hyphen-vediff.png
Remove-hyphen-diff.png

Removing a space near a line-break

This change is really hard to spot. See the small red line at the end of the second line.

Removing-a-space-at-linebreak-vediff.png

Comment annotating empty space

Edit first template

Editing the first template on the page shows a comment annotating an empty space and shows no content.