Page MenuHomePhabricator

Publish Technical RfC: new syntax for multi-line list items/talk page comments
Open, Needs TriagePublic

Description

This task represents the work involved with starting/publishing a technical RfC [1] to decide what syntax [2] ought to be introduced to enable people to write multi-line list items/talk page comments.

RfC

The version of the RfC below should supersede the version written in the RfC for multi-line comments Google Doc. Ultimately, what's included below should be used to populate the TechCom's "Create an RFC" template.

META

MOTIVATION
The current lack of explicit syntax for multi-line comments means…

  • Contributors are limited in the types of things (e.g. tables and images) they are able to embed in lists (read: indented talk page comments). This inhibits them from being able to communicate about and collaborate on components like navboxes, series templates, and infoboxes within indented comments on talk pages. When contributors really need to use such features, they'll sometimes break out of the indentation structure, making it harder for readers and algorithms to understand the structure of a conversation.
  • Contributors are not able to create visual line breaks within talk page comments without using HTML code or local templates.
  • Contributors face a higher risk of markup errors contained with talk page comments posted using DiscussionTools "leaking out" and corrupting content elsewhere on the talk page.
  • Contributors who use screen readers have a more difficult time understanding conversations, and subsequently participating in them, because the tools they use are not able to properly narrate/speak/announce the comments in a talk page conversation. Source
  • People using features like the new Reply Tool are not able to use templates, tables and extensions in the tool's visual mode.

ADDITIONAL BENEFITS
In addition to the resolving the issues listed in the "MOTIVATION" section above, the introduction of new syntax for multi-line comments would unlock new features like:

  • Contributors could more reliably edit specific comments on talk pages that are wrapped in the new multi-line wikitext syntax
  • Comment parsing would become more reliable, which would make it easier for contributors to build new gadgets that extend talk page functionality

REQUIREMENTS

  • New syntax for being able to write components that span multiple lines inside an indented list item.
    • Where a "component" could be: a table, template or an extension (including references)
  • This "new syntax" must meet the following conditions:
    • New syntax must not break existing content on talk pages
    • People need to be able to recognize the new syntax as being wikitext
      • Read: the syntax should not be easy to mistake as being part of the message people are trying to communicate in the comments they post.
    • People should be able to easily understand the meaning/function of the syntax by reading it context
    • New syntax needs to be interoperable with existing-and-future list-item talk page markup
    • New syntax must work across all languages and be reasonably convenient to input using different text input methods.
    • New syntax must be compatible with the core parser.

POTENTIAL APPROACHES
This section, once completed, will contain the potential solutions that have surfaced in conversations thus far.

  • Approach Name
    • Description of approach
    • Advantages of approach
    • Disadvantages of approach

BACKGROUND INFORMATION
The background information below does not seem to be a requirement of the "Create an RFC" template. I am including it here in case it's helpful context for those interested in the RfC.

This RfC is part of the Talk Pages Project, a project the WMF's Editing Team is leading. This goal of this project is to help editors, across experience levels, communicate more efficiently on wiki.

This project is the result of the Talk pages consultation 2019, a five-month-long consultation in which volunteers from at least 20 wikis and staff from the Foundation defined a product direction for building better tools for on-wiki communication.

A key outcome of the Talk pages consultation was the following product direction which continues to determine the design and implementation of the new tools and features we will introduce as part of this project:

Wikitext talk pages should be improved, and not replaced. We will build a new design on top of wikitext talk pages that changes the page's default appearance and offers key tools. This new design should communicate to the user that this is not a content page, and help the user interact appropriately with the tools. | Source

EXPLORATION

Done

StatusActionOwnerTicket
-Document the approaches that have been discussed so far (see: T230683), and the advantages and disadvantages associated with each one, here: RfC for multi-line comments [RfC for multi-line commentsApproaches do not need to be defined upfrontn/a
-Document the approach we favor and why we favor it here: RfC for multi-line comments [RfC for multi-line comments.Approaches do not need to be defined upfrontn/a
Determine code stewardship@marcellaT246960#6380444
Determine "Affected components" in the "Meta" section aboveEditing / Parsing Engineering
#todoPublish RfC via "Create an RFC" template@JTannerWMFT246960
#todoMake relevant stakeholders aware of RfC's existence@Whatamidoing-WMFT258850
#todoAdd link to mw.org RfC page to Help:DiscussionTools/Reply tool visual mode limitations@ppelberg

  1. https://www.mediawiki.org/wiki/Requests_for_comment
  2. Discussions about potential approaches can be found here: T230683: New syntax for multiline list items / talk page comments

Event Timeline

ppelberg created this task.Mar 5 2020, 12:56 AM
Restricted Application added a subscriber: Aklapper. · View Herald TranscriptMar 5 2020, 12:56 AM
ppelberg assigned this task to dchan.Mar 5 2020, 3:02 PM
Alsee added a subscriber: Alsee.Mar 15 2020, 9:56 AM

Why is the information not posted for public access? Maybe this is a silly suggestion, but doesn't the Foundation have a global scale wiki farm for public access content hosting?

The document is private while the team finishes the first two tasks listed in the "Done" section of the task description [1]. Once those are completed, the RFC will be posted on-wiki, as you suggest, for public comment.


  1. Document the approaches that have been discussed so far (see: T230683), and the advantages and disadvantages associated with each one and document the approach we favor and why we favor it here: RfC for multi-line comments [RfC for multi-line comments.
ppelberg removed dchan as the assignee of this task.May 2 2020, 2:24 AM
ppelberg updated the task description. (Show Details)

We are waiting on the go ahead from @ppelberg

We will not resume work on this task between now and the end of this quarter (30-June-2020).

Instead, we will revisit the question of "When should this work happen?" when we begin planning for next quarter (July - September, 2020) at the beginning of June, 2020.

JTannerWMF moved this task from Backlog to FY2020-21 on the Editing-team (Tracking) board.

T253150: Problem with template transclusion and switching editors: an example of a ticket that would benefit from this new syntax.

Meeting outcomes: 25-June
Today the Editing and Parsing Team met and came to agree on the following...

  • RfC timing: Editing will publish and complete this RfC by the end of September, 2020 (FY2020-21/Q1)
  • Implementation timing: The earliest the Parsing-Team--ARCHIVED could implement the new syntax that is decided upon through the RfC process would be January, February or March 2021 (FY2020-21/Q3)
  • Core parser compatibility: Whatever syntax is implemented must be compatible with the core parser.
    • This consideration is now represented within the "Project requirements" section of the RfC for multi-line comments... doc as, "New syntax must be compatible with the core parser."

Per conversation between Editing and Parsing the RFC can be published without our team expressing an opinion about a particular syntax because all that has been proposed will be equally effective in allowing multi-line comments and compatible with existing tools and pages.

Next steps:

  • Publish
ppelberg updated the task description. (Show Details)Jul 25 2020, 12:55 AM
ppelberg added subscribers: marcella, Esanders.

Update
Yesterday, @Esanders and I finalized the "Acceptance Criteria" (see doc: RfC for multi-line comments).

Next steps

ppelberg updated the task description. (Show Details)Aug 15 2020, 1:33 AM
ppelberg updated the task description. (Show Details)Aug 15 2020, 2:39 AM

(The task description's "RfC" section now includes the content we'll use to populate Tech-Com's "Create an RFC" template)

Tacsipacsi updated the task description. (Show Details)Aug 15 2020, 12:31 PM
Tacsipacsi added a subscriber: Tacsipacsi.
Esanders updated the task description. (Show Details)Aug 17 2020, 5:30 PM

META
Affected components: Legacy parser, Parsoid, wikitext specification

Thank you for updating the above in the task description, @Esanders.

A clarifying question for you: Does "Legacy parser, Parsoid, wikitext specification" describe, "...which components benefit from the problem being solved?" [i]

...I ask the above in response to @JTannerWMF sharing that it may not have been clear what "Affected components" meant.


i. https://www.mediawiki.org/wiki/Requests_for_comment#Start_an_RFC

ppelberg updated the task description. (Show Details)Aug 25 2020, 4:52 PM

Code steward
@marcella confirmed with @ssastry that the Parsing Team will be the code stewards for the code changes this RfC produces. The task description has been updated to reflect this.

ppelberg updated the task description. (Show Details)Aug 26 2020, 3:39 PM
ppelberg added a comment.EditedAug 26 2020, 3:42 PM

Potential approaches
As discussed yesterday, @Esanders is going to document the "potential approaches" that have been discussed so far. These approaches will be gathered in a doc that I will then transfer to the task description.

Once the potential approaches have been added to the task description, the RfC can be posted.

Note: Ed, when drafting the "potential approaches" doc, for each can you please include the information in the bullet list below?

  • Approach name
    • Description of approach
    • Advantages of approach
    • Disadvantages of approach

In the category of "additional benefits": It'll work on any wikitext page. The problem of 'markup errors contained with talk page comments posted using DiscussionTools "leaking out" and corrupting content elsewhere' is not unique to either DiscussionTools or to talk pages. You could use this syntax to limit the damage caused by a incorrect syntax or a malformed template even if you don't know how to fix the underlying problem.

ppelberg added a comment.EditedSep 4 2020, 7:26 PM

Mediawiki.org page
Considering editors not familiar with or accustomed to talking in Phabricator will be affected by the changes this RfC produces, @Whatamidoing-WMF suggested we create a page on mediawiki.org for people to learn about and share feedback about the RfC.

The draft of that page can be found here: https://www.mediawiki.org/wiki/User:PPelberg_(WMF)/sandbox.

@Esanders will summarize the approaches

@cscott's summary at T230683#5787721 is comprehensive. Do we need to shorten it or can we include it as it?

The Editing & Parsing teams currently prefer the "heredoc" syntax.

@cscott's summary at T230683#5787721 is comprehensive. Do we need to shorten it or can we include it as it?

I took a pass at synthesizing what @cscott put together and narrowing the scope of comments we include to those that speak directly to the #Requirements this to-be-decided-upon syntax is intended to meet.

  • @Esanders, can you please review the edits I've made [i] and ensure that A) I've accurately synthesized the discussion on T230683 and B) I've included the comments pertinent to the #Requirements?

I took a pass at synthesizing what @cscott put together and narrowing the scope of comments we include to those that speak directly to the #Requirements this to-be-decided-upon syntax is intended to meet.

  • @Esanders, can you please review the edits I've made [i] and ensure that A) I've accurately synthesized the discussion on T230683 and B) I've included the comments pertinent to the #Requirements?

Looks good to me.

We need to deprioritize this for right now but want to revisit in Q3.

Izno added a subscriber: Izno.Nov 13 2020, 3:45 PM