Wiki diff

So I've been thinking a little more about how best to show diffs between versions of a wiki page. David makes the excellent point that diffing the markup is at best a half-solution. It's somewhat inelegant as it forces readers to mentally translate the markup in order to really understand what changes have been made. And it's needlessly confusing for non-technical users: people who are readers but not authors.

So I've decided to do a survey of how different systems handle this task and see if we can find a better solution to the problem. Be sure to click the links throughout the post to see screenshots.

Confluence

Confluence’s diffing does a good job of showing the changes in a page’s markup. It highlights additions and deletions with red and green lines. And it clearly indicates exactly which words have changed, rather than just highlighting the entire line or paragraph. But Confluence’s diffs are missing two important pieces of information: there are no authors’ comments and there are no links to the previous and next versions of the page. And while the diffs are fairly easy to find (on the info tab), it is very difficult to find the actual page in an older version. One has to click to view the diffs, and then click again on the tiny version link at the top of the diff page. (See the whole thing in action here.)

However, when Confluence does display an older version of a page, there is a clear warning that this is an out-of-date version and there is no opportunity to edit it. But here as well, there is no way to easily step through next and previous versions; there is only a link to the current version. And we’re still faced with the core problem: to see what has changed, we have to read diffs of markup.

SocialText

SocialText is similarly limited. It offers the ability to diff only between adjacent versions. It doesn’t allow the author to make comments when changing a page. There is no way to step through revisions. It does offer an easy “restore this version” link, which I found handly. But SocialText, too, diffs the markup rather than the content.

However, the markup diffs are more limited than Confluence offers. It appears to mark only full paragraphs. It doesn’t mark individually changed words. And there appear to be some problems with the diffing algorithm as well. It had trouble accurately telling what was changed and what was merely moved. And in one example, I both added and removed text from a single paragraph, but the diff marked the entire paragraph red, with no indication of the specific words I had changed or added.

JotSpot

JotSpot offers similar functionality to the first two examples. It only offers diffs between adjacent versions. There are no author comments. But JotSpot takes a different tack when showing the actual diff. Instead of markup, we get a side-by-side comparison of the page content. Unfortunately, there is nothing to mark the actual changes: it’s left up to visual inspection.

There is, however, a serious problem here. When viewing an older revision, there is no warning that this is not the most recent version of the page. Worst of all, there’s still an edit button at the bottom, which allows you to edit the older version of your page. Hitting the save button will, without warning, save your edits as new revision, clobbering all the changes that are more recent than the old version you just edited. [UPDATE: As Reuben points out, the old version is still around and you can get back to it if needed. And do keep in mind, this is still beta software, so they may well fix this problem before release.]

XWiki

XWiki offers some improvements over the three wikis examined thus far. It gives us the ability to diff between any two versions — not just adjacent ones. But best of all, XWiki offers three distinct types of diffs: wikidiff, sourcediff (or markup) and htmldiff (or content). (Try it out here.) This is an excellent feature. I’m glad someone thought to implement multiple styles of diffs for different types of users.

XWiki is nonetheless missing a few features. There are no author comments. And there is no warning when viewing an old version. But the edit button takes you to edit the current page — so at least it’s safe, though slightly confusing.

Wikipedia

Wikipedia has the best diffing interface that I could find. It can diff between arbitrary versions. It allows author comments and makes them visible even when viewing the actual diff. There is an easy interface to step forward and backward through the diffs. And also, when viewing an old revision of the page, it’s clearly marked and there is a convenient way to easily step forward and backward through the page history.

Unfortunately, these forward/backward links are not as useful as they might be. When clicked, Wikipedia simply reloads a newer or older version of the entire page. So there is no way for the reader to actually see what has changed between versions.

While Wikipedia has a almost flawless interface for viewing markup-diffs, and while it makes a good effort at allowing the user to navigate through time by offering previous and next version links, it still doesn’t make it easy for a reader to comprehend the content changes.

Going Forward

I think an ideal wiki will want to offer the best of these features:

1. Allow arbitrary diffs between any two revsisions of a page.
2. Provide diffs of both markup and content.
3. Clearly mark individual words changed — not just lines.
4. Provide an easy way to step forward and backward in time.
5. Make it easy for the reader to see what has changed from version to version with coloring.
6. Allow authors to comment on each page change.
7. As a safety measure, make it very clear when the user is viewing an out-of-date page and prevent the user from attempting to edit it.

The hardest feature to implement will be, I predict, accurate and granular diff coloring. But Wikipedia and Confluence have managed it on the markup side. So I think it must be possible on the content side. In any case, these suggestions could go a long way toward answering the common complaints about understanding changing content on a wiki page.