Community Tech/Section Name in Diff

Introduction

The Section Name in Diff (SND) project aims to enhance the diff experience. Under the current system, users cannot see the applicable section name in the diff in many circumstances. This behavior often obscures the context behind the diff. With this project, we plan to add the section name, so that users can better understand diffs in relation to page structure. This project was the #9 request from the 2019 Community Wishlist Survey. We look forward to community feedback on the Talk page.

How Sections Work on Wiki Pages

A section is a header that helps structure a page. You can see an example of a section name (“History”) and subsection name (“Classical Era”) and (“Feudal Era”) in the screenshot below. You will see that the primary section header is marked by a line, spanning the page. The subsections are displayed in bold. A page can have multiple sections and subsections.

In wikitext, one adds sections in the following way:

== Section ==
=== Subsection ===
==== Sub-subsection ====

In VisualEditor, one adds sections via drop-down (see example below).

Example of accessing section headers via VisualEditor

When Section Names Display in Wikitext of the Diff

A diff (which comes from “difference”) is a page that compares two versions of a wiki page. You can access a diff page from many places, such as Special:RecentChanges or Page History. When you view a diff page, you can see the author name (if any) and revision changes in wikitext. The page also displays revision details, such as the edit summary and edit tags.

The section name associated with a revision is not always displayed in the diff. However, in certain cases, it is displayed. First, this occurs when someone adds or edits the section name within the revision. For this reason, the contents of the section name will display (in wikitext format) in the diff. As you can see in the example below, one editor changed the name of the section from “Medieval era” to “Feudal era.” For this reason, the section names are included in the diff. Furthermore, if the editor created a new section, the section name would display in the diff.

Second, the section name displays when a revision occurred in the line before or after the section title. For example, you can see multiple section headers (“Sources,” “Contemporaneous Sources,” and “Historical Sources”) included in the screenshot below. This is because the revision included a change to the word “archeological,” below the section header for “Contemporaneous Sources.”

When Section Names Display in Edit Summary of Diff Page

The edit summary is a brief explanation of a revision. When users edit a page, they are provided with a text field, below the editing area, for the edit summary. It is considered good practice to include an edit summary, but not all editors add them.

Sometimes, the edit summary displays in diff pages, and the edit summary includes the section name. This happens in a particular circumstance: a section edit. Under this scenario, the editor chooses to edit a particular section of a page (via the “Edit” link, next to the section header). The editor is then redirected to the edit view, and the section name is auto-populated in the edit summary (see “Feudal Era” in screenshot example below).

Section name (“Feudal Era”) automatically populated in the Edit Summary

Consequently, when the editor chooses to “Publish Changes,” the section header is included in the edit summary. The edit summary is displayed on top of the diff content (see “Feudal Era” in screenshot example below, on the right side).

Example of a diff with section name (“Feudal Era”) in edit summary for new version (at left).

The section name in the edit summary is useful, but it’s insufficient. First, the section name is only displayed in the edit summary, rather than in wikitext. It is often preferred to have information within the wikitext, since it can be more easily extracted and analyzed for various purposes. Second, there is no proof that the section name is accurate, since the editor can manually edit, alter, or remove it. Third, the edit summary may only display the section name for one version, rather than both versions, as seen in the screenshot above. Fourth, the edit summary doesn’t display in all cases—only in diff pages for section edits.

When No Section Names Display in the Diff

There are times when the section name is not displayed in the diff. For example, you can see a diff associated with the “Japan” article in English Wikipedia below. The particular revision can be found under the “History” section and the “Feudal Era” subsection in the read view. However, the section and subsection are not displayed in the wikitext or edit summary for either version. The only indication of the location of the content is found in the line number (i.e., Line 111), which is not displayed in read view.

Example of no section name in diff or edit summary.

There are a few reasons why no section name displays on diff pages. First, the editor may have chosen to edit the entire page, rather than one section. This may occur when someone wants to edit multiple sections, or simply because they first saw the “Edit” link at the top of the page. As a result, the section name isn’t included in the edit summary. Furthermore, the section names will not display in the diff, if the editor has not created/edited a section or made a revision to the line above/below a section header.

Second, the user may have deleted the section name in the edit summary. This may have occurred by accident, or the user may have intentionally decided to remove it. No matter the reason, the result is that the section name no longer appears in the edit summary.

Third, there may be a “mixed” case, in which the section name in the edit summary is different than the section name in the wikitext. This occurs when the editor creates a new section within a section edit. For this reason, the original section name is displayed in the edit summary, and the new section name is displayed in the diff content. This behavior may or may not be appropriate, but we wanted to include it in order to cover all cases.

Why People Want to See Section Names in the Diff

There are many reasons why someone would want to see the section name in the diff.

First, the user may want to know the general context behind an edit. The inclusion of the section name helps provide a more complete picture of this context. The user can see the overarching theme of the section and edit in question. They can also understand how the section may function in the context of the page as a whole.

Second, the user may want to determine if the edit is appropriately placed. At times, the edit may be accurate and properly sourced. However, it may be placed in an incorrect part of the page, as determined by the sections. If the user can see the edit, they can see if the edit is perhaps inappropriate for the given section.

Third, the user may want to determine if the section is still accurately named. The content in the section may have changed, and as such, the section name may need to be updated. In this case, it may be appropriate to display the name of the associated section, so that users can make such assessments.

Fourth, the user may want to verify the section name, as displayed in the edit summary, against the actual section name in wikitext. In this case, the user may see the section name displayed in one or two versions in the diff. However, there is no guarantee that the section name is accurate and has not, in fact, been altered by the user. Therefore, the inclusion of the section name in wikitext would provide a higher level of accuracy and reliability.

Fifth, the user can avoid scenarios in which the section name is included in one, rather than two, edit summaries. This helps users access cleaner and more easily comparable diffs. Ideally, users should receive reliable information that can be reflected in both versions, rather than counting on data from one version to accurately reflect the other.

Open Questions

Have we covered the primary ways that editors can currently see the section name in the diff?
Have we covered the primary reasons why section names are excluded from diffs?
Have we covered the primary reasons why editors want the section name in the diff?
What are the most common reasons you, personally, want the section name in the diff?
How and in what format would you prefer to see the section name included in the diff?
Any other feedback on the project?

Please share your thoughts on the project Talk page!

Important Links

Wishlist proposal, discussion, and votes
Phabricator tickets: T242264, T231698

Status Updates

December 15, 2020

This wish has been partially resolved by work done by the Editing team. The section name has been included in the visual diff.

April 8, 2020

Hello, everyone! We have begun the early planning stages of this project. As a first step, we have brainstormed a few ways that the section name can display in the diff. Now, we would love your feedback! Please be aware that these are simply ideas to prompt early discussions, but we’ll need to do more research and planning before we can commit to any designs. In the meantime, please check out the ideas we have shared below and let us know your thoughts on the Talk page. Thank you!

Idea #1: Replace line number with section name

Here, you will see that we have replaced the line number with the section name. This will occur in most cases, except in code files, like JS and CSS, where line numbers are important. The section name, if clicked, will link to the section on the page itself. The edit link will be shown when viewing the most recent version of the section.

Idea #2: Section name in wikitext (top)

Here, you will see that we have kept the line number. The section name is included at the top of the relevant section, and it is displayed in wikitext format.

Idea #3: Section Name in wikitext (top and bottom)

Here, you will see that we have kept the line number. The section name is included at the top and bottom of the relevant section, displayed in wikitext format. You can also see links to the section of the page and edit links, since the most recent version of the section is displayed.

Idea #4: Visual Diff

When using the visual diff, the section heading is displayed in the same format as seen when editing.

Open Questions

What do you think of the display of the section name in idea 1?
What do you think of the display of the section name in idea 2?
What do you think of the display of the section name in idea 3?
What do you think of the display of the section name in the visual diff (idea 4)?
What are the most common methods (e.g. via RecentChanges, History, before publishing changes, etc) that you use to access diff pages?
What are the most common reasons that you access diff pages?
What kind of information (e.g. mistakes, vandalism, context, etc) are you looking for in the diff?
What actions (e.g. revert, thank, make further changes, etc) do you usually take after looking at a diff?
Anything else you would like to add?

We invite you to share your thoughts on the Talk page. Thank you!