Help:Diff

What is a diff? (Natalia/Sandister)
A diff, short for difference, displays the changes between two versions of a page. Diffs are a fundamental component of navigation and content moderation on Wikimedia projects.

The platforms in the wiki ecosystem have several versions of a Diff depending on which device and installation of MediaWiki is being used. This is a screenshot of the user interface example of wikidiff2.

How it looks
This example shows the top of the diff page (some of the links are dummies). The older version is shown on the left, the newer version on the right.



Explanation of colours
Unchanged text is dark grey on light grey (only parts before and after changed text are shown). Paragraphs which have changed are black on white, with an orange border on the old version side and a blue border on the new version side. Inserted and removed text is highlighted with the border color and bolded. Where whole paragraphs have been removed or inserted, no highlighting or bolding is applied and the other side is blank.

When and why to use a diff?
The main reason to use a diff is to review a specific change to an article made by yourself or someone else. There are many possible reasons to do this:


 * To help find instances of vandalism in an article
 * To determine when a section, sentence, or word was added or removed
 * To determine which editor made a given change
 * As a jumping off point to further actions as the diff contains edit, undo, and thank actions as well as links to the editing user's page.

How to navigate to view a diff?
The most common way to view a diff is through the "Revision history". This is accessible via the "" tab. From there, you can use "" to view diffs of single revisions, or use the radio buttons and the "" button to view diffs across multiple revisions.

Most special pages that list changes will usually include links to diffs, such as Special:RecentChanges, Special:Watchlist, Special:Contributions and Special:Relatedchanges.

Another way to view a diff is with the Special:Diff page. To use this, you must know the IDs of the revisions you want to compare. Revision IDs can be retrieved by looking at the  portion of a diff URL, where   is the diff ID. Additionally, you can use the value of the  parameter to get the diff of that revision against the previous one.

Components to a diff (sections, tags, etc.) (Karolin, Dom)
Below is a visual representation of the important components of a diff page which you will see when viewing the difference between two published changes.



Add +
When somebody has added new text, we find a + icon, we know that there has been an addition in the paragraph next to the symbol. The added words and characters will be highlighted and bold.

Remove -
When somebody has removed text, we find a - icon, we know that there has been a removal in the paragraph next to the symbol. The removed words and characters will be highlighted and bold.

Move
When somebody has moved text, one can clearly identify from where to where text has been moved. There's an arrow icon pointing out where the moved text went to.

Replace
We can see what has been replaced with new content when there's a + icon and a - icon next to the phrase where the change happened.

How to link to diffs?
Diffs can be linked to by copying the URL while viewing the diff - this URL has two parameters,  and.

Linking to a diff from outside a wiki can be done by using the full URL, for example:


 * https://mediawiki.org/w/index.php?diff=1242287

The diff special page makes it easier to create shorter URLs which redirect to diffs.

From within a wiki, these links can take the following forms:


 * → Special:Diff/1242287 – Shows the diff to the previous revision of the same page.
 * → Special:Diff/1242287/prev – Shows the diff to the previous revision of the same page.
 * → Special:Diff/1242287/next – Shows the diff to the next revision of the same page.
 * → Special:Diff/1242287/cur – Shows the diff to the current revision of the same page.
 * → Special:Diff/1242286/1242287 – Shows the diff between the specified revisions of the same page which may also be reversed, e.g. → Special:Diff/1242287/1242286, though one should avoid this.

These links may be used in the edit summary as well as adapted like any other internal links, e.g..

For example, the full URL  could also be written as.

By default, the later revision of the page is displayed in full below the diff - this can be turned off via a preferences ("") or by setting  in the URL. Links to diffs without the page text can be created:



How to report bugs?
Bugs should be filed on Phabricator under the tag.

What's the history of the diff?
Why would we use a diff view? (History)

Exceptionally good examples of documentation

 * https://www.mediawiki.org/wiki/Help:Extension:Media_Viewer
 * External: https://stripe.com/docs/billing/subscriptions/overview

Tips for documentation writing in general
https://www.mediawiki.org/wiki/Documentation/Style_guide