771730 - Design improvements for RSS inline diff

Status: VERIFIED FIXED

(developer.mozilla.org Graveyard :: Wiki pages, defect, P1)

Description

[Eric Shepherd [:sheppy]]

Attachment: screenshot of rss feed entry

I've attached what this looks like. There are a few problems here:

1. I have no idea what's changed here. How are we styling the differences (or are we)? I was expecting side-by-side output, but instead I see styled HTML that looks like it's simply repeated twice. Something needs to make this more readable.

2. It looks like the information about the type of change, number of words added/removed, etc has been removed. Please put it back.

Comment 1

[Eric Shepherd [:sheppy]]

FWIW this really needs to be improved by launch, since this feed will be the primary way we monitor site changes.

Comment 2

[Luke Crouch [:groovecoder]]

Good feedback. I tried to match as much of the MindTouch diff view as I could and I knew we would need to iterate. We're using python difflib [1] now, so we won't have exactly what MindTouch had. I have to say this is one area I was impressed by the quality of the MindTouch code. Anyway, here's what's in Kuma:

1. I started with a diff table but including HTML inside a feed is really tricky for us - hard to escape the table HTML without escaping the diff HTML. :( So I switched to this inline diff mode which is technically easier ...

The output uses <ins>piece</ins> for pieces that have been inserted, <del>piece</del> for pieces that have been removed, and <del>old-piece</del><ins>new-piece</ins> for replacements. So in the screenshot, it looks like "2" was added in two places, and "nobr" was removed. (Default styling is to underline <ins> tags and strike-thru <del> tags)

2. difflib can easily give a count of changes, e.g. 2 changes in the screenshot, but word count could be tricky. How vital is that? Would "Edited 3 areas" be sufficient?

Aside from that, we'll need to look at improving the inline diff formatting (inline styles maybe?) or try to bang out the table diff view. Which would you prefer?

[1] http://docs.python.org/library/difflib.html

Comment 3

[Eric Shepherd [:sheppy]]

(In reply to Luke Crouch [:groovecoder] from comment #2)
> Good feedback. I tried to match as much of the MindTouch diff view as I
> could and I knew we would need to iterate. We're using python difflib [1]
> now, so we won't have exactly what MindTouch had. I have to say this is one
> area I was impressed by the quality of the MindTouch code. Anyway, here's
> what's in Kuma:

FWIW, I always hated MindTouch's diff view. :)

> 1. I started with a diff table but including HTML inside a feed is really
> tricky for us - hard to escape the table HTML without escaping the diff
> HTML. :( So I switched to this inline diff mode which is technically easier
> ...

OK; the trick is it took me ages to realize what I was seeing. Some headings indicating "Previous version" and "New version" or something like that would help (or, better "Version from <date>" and "New version". I couldn't even tell which was the newer version.

> The output uses <ins>piece</ins> for pieces that have been inserted,
> <del>piece</del> for pieces that have been removed, and
> <del>old-piece</del><ins>new-piece</ins> for replacements. So in the
> screenshot, it looks like "2" was added in two places, and "nobr" was
> removed. (Default styling is to underline <ins> tags and strike-thru <del>
> tags)

It would be nice if the styling were a little more obvious; can we use some CSS to make removed text on a pink background and added text on green?

> 2. difflib can easily give a count of changes, e.g. 2 changes in the
> screenshot, but word count could be tricky. How vital is that? Would "Edited
> 3 areas" be sufficient?

We had counts before the diff was added, so that information was clearly coming from somewhere...

Also, is each area that changed listed separately? In that case, headings and maybe an <hr> between each changed area would be helpful.

> Aside from that, we'll need to look at improving the inline diff formatting
> (inline styles maybe?) or try to bang out the table diff view. Which would
> you prefer?

Let's tidy up the current look, then later on try to find a side-by-side look that works. I think we can make the inline diff "good enough" pretty fast, while a side-by-side would take some real investment of time.

Comment 4

[John Karahalis [:openjck]]

Renaming this and opening bug 771830 for side-by-side diffs.

Comment 5

[Luke Crouch [:groovecoder]]

Attachment: mockup of a better RSS feed

Comment 6

[[github robot]]

Commits pushed to master at https://github.com/mozilla/kuma

https://github.com/mozilla/kuma/commit/0f165b575eda01a2b2e32f10d8f48bada6361a39
bug 771730 - show table diff in feed

add tag diff

review diff; revision label on diff tables

colorize and test diffs

https://github.com/mozilla/kuma/commit/e40dea4a0954f0514c3ac2b9317a4087f69b9a7a
Merge pull request #528 from groovecoder/revision-feed-771730

bug 771730 - show table diff in feed

Comment 7

[raymond [:retornam] (inactive)]

fixed  https://developer.allizom.org/en-US/docs/feeds/rss/revisions