Don't take this document as authoritative or chiseled in stone. Parts of it are inaccurate or out-of-date. Caveat lector.

This document describes the design of a "feed"-like interface to enable users to better interact with the various projects they are working on. Flow has several "modules", one of which is a design for a structured user-to-user communication system.

Since this document was originally written, the concepts behind what Flow is and is not have become better understood and more solidified. This document has been updated accordingly and some sections may be split out into sub-documents.

Feedback is welcome on the talk page.

Flow as shown at Wikimania 2012
A Flow board mockup including watchlist, notice, and discussion aspects as of January 2013 (though it's missing a lot of stuff).

Note on Nomenclature


Nomenclature in this document (e.g., "Flow board") is product design facing and not user facing. User facing terms will very likely be different than those included herein.

In order to ease understanding, the following terms are defined:

Flow Board
This is the feed that users have of discussions and other items.
This is a single discussion (analogous to a Talk page "section"). Threads consist of Posts and Comments.
This is the first element in a Thread. It provides the title and has an author. There is one Post per Thread. Comments to the Post are children.
This is a reply to a Post or another Comment. There may be zero or more Comments to a Post.
This is used interchangably with Thread where the language gets weird.
Any atomic item that appears in a Flow Board.



One of the most confusing issues faced by users of Wikipedia (and MediaWiki in general) is that of "User Talk Pages." It is beyond the scope of this document to describe in detail all the problems involved with them and the interaction model problems they pose; however, a simple list could contain:

  • Conventions regarding user talk pages are opaque (e.g., indentation with colons, requirements for signature code, etc).
  • It is not clear as to where one responds to messages left. On my talk page, or yours? (see "talkback" templates)
    • Many people reply in different ways. Some reply on the other person's talk page, splitting the discussion. Others reply on their own talk page. People may or may not use talkback templates.
  • If a discussion is occurring on another user's talk page, there is no automated notification of replies.
    • This is further compounded because watchlists for active editors on large wikis tend to quickly become useless
      • And you have to know what a watchlist is, in the first place
      • You can use your contributions list as a pseudo-watchlist, but that doesn't show changes by other users.

Since communication between users is of paramount importance in a collaborative system, it is therefore essential that communication tools be easy-to-use, intuitive, robust, and responsive.

Initially, Flow will be focused on user-to-user communication and not general discussion.



An intuitive user-to-user discussion system will promote editor engagement and retention by eliminating several of the greater hurdles that new (and old) users face.

Feature Requirements


Flow discussions must allow for:

  • Automated posting, by bots or scripts.
  • Easy-to-use searching of posts
  • Multi-user interactions (e.g., 3 or more)
  • Addition of wiki markup in postings
  • Ultimate integration with the Visual Editor.



The following concepts are important to the usage of Flow and Flow-enabled systems.



The single most important concept behind Flow is subscriptions. Subscriptions are analagous to the current MediaWiki "watch" behavior but are able to be much more fine-grained.

For example, it is not possible to "watch" a single section on a standard Talk page - you must watch the entire page. Flow subscriptions allow for users to select individual Threads to subscribe to in addition to the option of subscribing to all discussions housed on the page.

The concept of subscription isn't just about watching discussion Threads. With Flow in its larger form, users will be able to "subscribe" to individual users as well (so that their activity flows into your feed, useful if one is mentoring), or subscribe to (join) groups (WikiProjects), or other systems (like the English Wikipedia's Signpost).

A user's subscriptions will be private (just as the watchlist is private).

Tagging and Filters


Clearly, with the volume of content that will be flowing through the subscriptions feed, some method of data organization and filtering will be required.

A popular feature request from users is the ability to have multiple watchlists (see e.g. this GSoC project and gerrit:16419). Flow solves this not by providing multiple lists but by allowing the user to tag pages within their watchlist and then apply filters based on those tags.

Flow allows for anything to be tagged that comes via a module. This includes discussions, users, watchlist items - whatever.



Flow content is produced by modules. Each module will publish content to the subscriptions board according to its own logic and provide interactive elements as makes sense.

The first two modules discussed are a user-to-user discussion module and a watchlist integration module (these are detailed below).

Future modules could include anything that would lend itself to a feed, such as Article Feedback posts, Feedback Dashboard items, Teahouse questions, Helpdesk questions, RFC discussions, etc.

Personal vs. External Views


MediaWiki does not distinguish between "your view" of your pages, and "other people's view" of your pages; there is no "home page" or "personal feed" other than the watchlist.

The primary interaction problem lies in the fact that there is no distinction between "how others interact with me" and "how I interact with others". Flow seeks to address this by introducing variable views on the data (called "first-person" and "third-person" views).

Let us take two hypothetical users, Ronald and Nancy. Each has their own Flow Board (see below).

If Nancy goes and looks at Ronald's Board, she is seeing the third-person view. She will see only Ronald's activity there:

  • Edits he has made to articles
  • Threads he has commented in
  • Administrative actions he has taken (page moves, etc.)
  • Other public things, as they become fed in via modules (e.g., "Ronald answered a question on the Teahouse...")

However, when she goes to her own Board, she will see the first-person view. She will see all of the above, plus:

  • Entries from her watchlist
  • Threads she has subscribed to but not commented in
  • Edits made by users she has subscribed to
  • Notifications of new Threads started on boards she subscribes to
  • Other things that she is subscribed to as they become fed in via modules (e.g., "A new question was posted on the Teahouse")

Flow Board


Each user will have a personal Flow Board. The Flow Board can be thought of as a single "activity feed" that mashes several things together (initially, user-to-user discussions and the watchlist).

A user's Flow board is similar to their talk page in that:

  • It is the place that other users go to leave messages.
  • It is the place that other users can view messages left by others.
  • It is also the place that the user can view his personal subscriptions feed.

Discussion Module


A major component of Flow is a user-to-user discussion system. User-to-user discussions are typically different than discussions about articles, policies, or processes in that they typically are not deeply threaded and rarely contain "!votes" or polls.

Most user-to-user discussions are fairly short and easily read chronologically.

Thread and comment "homes"


Currently, each talk section (as well as each LiquidThreads thread) is stored on its individual page, although transclusion can be used to multi-home discussions (impossible with LiquidThreads). This is problematic because users don't necessarily know where to look for the conversation threads that they are engaged in. For prolific editors this can be a nightmare of open tabs and so forth.

Flow seeks to solve this problem by removing the concept of a "home" for a given Thread. Threads are "owned" by all users who have interacted (subscribed) with them; they will appear in all feeds.

Thread Subscriptions


It should be possible to subscribe to Threads without actively engaging in the Thread (replying to a comment).

Users will be able to subscribe to all discussion activity on any user's Flow Board. This would greatly improve the situation with regards to mentoring, for example, or watching possible editors who work in bad faith. This is analogous to "watching" someone's Talk page.

Active vs. Passive subscriptions


Flow will make a distiction between active and passive subscriptions to Threads.

An active subscription is one on a Thread that the user has directly subscribed to, either by intentionally subscribing to it or by commenting in it.

A passive subscription is one where the user is subscribed to another user's Flow Board, but has not engaged in the specific Thread.

These will display differently within the Flow Board.

Actively subscribed Threads will display as "open" and will have interaction controls. They will also be subject to "staleness filtering" - when the Thread has activity, it will bubble to the surface in the Flow Board.

Passively subscribed Threads will simply display as a line item in the feed, with controls that will allow the user to view the Thread (and possibly subscribe to it, promoting it to an "active" subscription).

Thread subject versus replies


Threads are analogous to talk page sections. They have a subject heading and an original author.

There is a distinction that must be drawn between the original subject of a Post to a Flow discussion and replies to it.

Consider a template left for a user by WikiLove. The template is the original Post. If the user then replied to it, this would be a comment and tied to the original Post (which is the WikiLove template).

Minimal Interface


Postings in Flow discussions must have a minimal interface. Commenting does not require the full weight of the editor, for instance (even if they are wikitext entries).

Activity notification


Flow will automatically keep track of Posts and Comments that the user has seen. If a Post or Comment makes its way into the viewport, it will be marked as "read."

Threads that have unread Comments will be called out to the user. Additionally, they will "bubble" to the surface according to last-modified chronology.

Controls will be provided to allow the user to mark all Threads and Comments as read.



By its very nature, Flow Boards are auto-archiving. Elements in the board simply "fall off" the bottom visually but are still there and may be discovered through scrolling or pagination or simply searching for them.

Thread expansion and collapse


In order to reduce visual clutter, Threads with multiple Comments may need to be collapsed after a certain comment-count threshold is met (determined via user testing; ideally configurable on a per-installation basis).

It is entirely possible that this is not required, but it is something that should be accounted for in designs.

Comment privacy


Currently, any user may edit talk page postings by any other user. This is a behavior that is frankly alien to most users of discussion systems; they (rightfully) believe that their words are their own and do not expect others to "vandalize" them.

Accordingly, Comments in Flow Boards are only able to be modified by the user who created them or an administrator. When a Comment has been modified, a notice will be included saying that the comment was modified, when this happened, and who did the modification.

Collaborative Post setting


Flow Posts should have a setting that allows them to be modified by anyone. This bit will be set when the Post is originally made.

Collaborative Posts will be called out specially. There will be no avatar associated with the Post, but a list of all contributors will be included.

Moderation controls


Flow Threads, Posts, and Comments must be compliant with standard MediaWiki moderation controls. Administrators must be able to delete individual Comments or entire Threads.

Additionally, oversight functionality must be included.

Elimination of User Talk


A major question to be asked is whether or not a user's talk page be disabled and removed if they have been "Flow-enabled".

Reasons for keeping talk pages alongside Flow boards:

  • Some bots/scripts/systems may break if a talk page is non-existant
  • Some users are change-averse and will want to use talk pages exclusively
  • Flow cannot account for all the use cases that talk pages cover being that talk pages are free-form.

Reasons for removing talk pages from Flow-enabled users:

  • Additional page is likely redundant; will be unused
  • Additional interface clutter
  • Increased user confusion about where discussions happen
    • Especially if other users decide to post to the talk page rather than the Flow Board.

Process for "Flow-Enabling" for a single comment


One possibility would be on a per-section basis. Basically a UI would be surfaced next to each section area for the user of the talk page would allow the user to click to reply in Flow. At that moment:

  1. The section data would be copied as a new Thread [since the actual user-talk may be difficult to follow, this is prone to error and may copy the entire discussion into the Post in the Flow Thread]
  2. Existing commenters to that section should be added as subscribers to the Flow discussion [determination may need to troll/track revisions so some simplification might be done here]
  3. A change is done to the user talk to delete the discussion and link the Flow Thread
  4. The user has interface elements surfaced to reply within the Flow Thread (so that when the reply is saved, participants will receive notification)

Process for "Flow-Enabling" for entire page


The argument for this would be certain users want to upgrade their user talk to Flow Boards. If this is done some the process above for a single comment would be applied multiply with some changes:

  • No UI reply sufficed
  • No link into the discussion would be put in place, instead requests to the user's talk would be redirected to user's Flow discussion
  • Some mechanism for archiving the revisions and then deletion of the revisions from the revision table would be done

Data Structure


To prevent the complexities and feature-creep associated with running Flow discussions on the current revision text stuff, the data store for this would have to be in a new horizontally-scaled data structure in MediaWiki core.

Watchlist Module


The watchlist module will feed changes that occur in the user's watchlist to the Flow board. Users will then be able to view revisions in situ and even act upon them (clicking to open and view diffs in-line, for instance).

Archived elements


By their very nature, watchlist entries go "stale" after a certain point and fall off the watchlist. It may be desirable not to include stale watchlist entries when the user goes through older entries in their feed.

Tagging Infrastructure


Flow introduces the concept of tagging to MediaWiki. Tags will be used for element curation. Tags are personal and private to the user.

The user's Flow Board may then be filtered by tags (a "tag search"). Only elements that have been given the specific tag or tags will appear.

Initially, tags can be applied to Threads, Articles, and Users. This allows fine-grained filtering of visible elements in the Flow Board.

Tag searches and intersections


Tag searches should be able to be performed through the Flow Board's search functionality and be done in natural language if at all possible.

Tag searching should also understand element type. For example, "article:blp" might only display watchlist edits to articles that have been tagged "blp". Likewise, something like "thread:policy" might pull up Flow Threads that have been tagged as "policy". This allows users to develop their own workflows and searches (imagine being able to search for edits to BLPs that were made by users who have been tagged as vandals).

User should be able to perform tag intersection searches. It may not be possible to include both AND and OR operators; if so, only AND is required. Operator nesting is not desired.

Tag searching does not make sense when viewing the Flow Boards of other users, so this functionality would be disabled in the third-person view.

Things to Consider (Jorm's Scratchpad)

  • Users who interact with Flow boards who are not themselves Flow-enabled.
  • How do posts/replies to a Flow board appear in a watchlist?
  • IP Editors
  • Connection to GlobalProfile
  • Banner messages/pinned messages
  • Search mechanics
  • Archive/close thread
  • Thread bookmarks?
  • Muting/blocking
  • Transclusion
  • For users who enable Flow who already have a talk page, what happens?
  • Watchlist integration
  • Users will want to be able to view their own feed as others see it.

Filters and Sorts scratchpad



  • Text search
  • User search
  • Tag search
  • Module type search


  • Chronological
  • Activity

See also