Structured Discussions

Flow is a project of the Collaboration team at the Wikimedia Foundation to build a modern discussion and collaboration system for Wikimedia projects. Flow provides features that are present on most modern websites, but which are not possible to implement in wikitext. For example, Flow automatically signs posts, threads replies, and permits per-topic notifications.

The main goals for the Flow project are:
 * to make the wiki discussion system more accessible for new users
 * to make the wiki discussion system more efficient for experienced users
 * to encourage meaningful conversations that support collaboration

Flow has been deployed on user talk and wiki-wide discussion pages on various languages and projects, as well as Mediawiki.org – see Flow/Rollout. In September 2015, the team released an opt-in beta feature for wikis that request it, which will allow users to turn on Flow for their own user talk page – see Flow/Request Flow on a page.

Development status
As of February 2017, Flow is still being actively maintained. The team is supporting the product and will continue to fix bugs and to make sure that people who are using Flow continue to have a good experience. Communities can try Flow, knowing that there are some limitations and that additional major features will probably not be added during the next few months.

However, Flow has not scheduled for major development since the middle of 2015. "Not in active development" means that significant new features are not being created at this time. The Collaboration Team remains interested in the project and in providing an improved system for structured discussions. Some communities have decided to use Flow and are asking for support.

For the near term, Collaboration team is focusing on Edit Review Improvements project. However, after that work is done, there are some often-requested areas for improvement in Flow which the team plan to improve. To make decisions about the way forward in this area and future developments (scheduled for June 2017 ), a survey has been sent to many Flow users in September 2016, results published in January 2017. Those results will be used to support a decision for the Wikimedia Foundation’s Editing department plans for the next fiscal year.

Rationale
New users on English Wikipedia have become less and less likely to participate in on-wiki discussions, in spite of a growing and mostly automated body of messages directed at them. We also know that free-form wikitext talk pages present a significant barrier to new users  and even some experienced users.

In addition, experienced users often employ a suite of workarounds to help them manage and keep track of the many ongoing conversations that they're involved in, using tools that aren't necessarily well-suited to the task. For example, watchlists and diffs are page-level tools, making it hard to distinguish between the conversations that users are interested in and the ones that they're not. Experienced users can waste a lot of time checking diffs on an active talk page, especially if the most active conversation isn't the one that they're interested in following.

We believe that user expectations for a modern discussion system are increasingly diverging from the reality of talk pages today, and that all of our users deserve discussion and collaboration software that meets their needs.

Users expect a modern and intuitive discussion interface. Talk pages—as a discussion technology—are antiquated and are not intuitive.

Users are surprised by the cultural norms of the community. Many things about the culture that has grown up around talk pages (such as "talkback" templates or being able to edit other people's comments) are confusing. That is not to say those conventions are wrong, merely not what those users are prepared for.

We believe that a modern user-to-user discussion system will improve the projects. Better methods for collaboration will improve collaboration, which will improve all of the projects.

Q1 (July-September 2014)
User-facing features:
 * Subscriptions:
 * ✅ Subscribe to individual topics
 * ✅ Auto-subscription for topic user has created or participated in
 * ✅ Subscribing to Flow board = notifications for new topics on that board


 * Notifications:
 * ✅ Roll-up notifications for activity, one notification item per topic
 * ✅ Clicking on a notification takes you to topic page, with unread messages marked with color
 * ✅ Read/unread state for Flow notifications
 * ✅ Mark all as read


 * ✅ Log item improvements for Watchlist and Contributions (initial step done, but bugs in Contributions need to get fixed)
 * ✅ Hide feature redesign -- actually removing hidden threads from the page, still accessible through history and contributions
 * ✅ Mobile UI and design - board and threads are done, we'll do update to mobile Echo later

MediaWiki changes:
 * ✅ Create a namespace for topic pages
 * ✅ Notifications: dynamic read/unread states

Community partnerships:


 * ✅ Work with the Co-Op team on changes that we'd need for Flow to be useful to the Co-op.
 * ✅ Work with the French WP Forum des nouveaux, ditto

Quarterly review following Q1:

Q2 (October-December 2014)
User-facing features:
 * ✅ Table of contents
 * Search on a Flow board -- (coming in Q3)
 * Structural UI changes to enable editing other people's comments -- (partly done in Q2, more in Q3)
 * ✅ LiquidThreads: Transition to wikitext or Flow (based on Andrew's script)
 * ❌ A more sophisticated version of subscribe to a board -- giving users more options on how notifications appear in Echo and in watchlists. (Not done in Q2, but it will definitely come up later on.)
 * ✅ Review of fixed width and indentation levels. (Just a review. Not a promise.) If we keep fixed width, we need a solution for tables and galleries. (review done, changes coming in Q3)
 * ✅ Special:EnableFlow to have a more scaleable solution for creating new Flow boards (partly done in Q2 with Liquid Threads conversion, more in Q3)
 * ❌ Turn summarize into a scratchpad area of full wikitext, connected to the conversation. Actual design TBD. (not done in Q2, but it will definitely come up later.)
 * ❌ "Resolved" function -- mark a topic as resolved. Then we build a sort for resolved/unresolved. (Just "closed" in Q2, but we'll return to this.)
 * ✅ Visual Editor integration with Flow input boxes (coming in Q3)

Community partnerships:
 * ✅ Continue to work with Co-op and Forum des nouveaux
 * ✅ Establish more partnerships with communities in other languages, TBA (working with Catalan, Portuguese)

Quarterly review following Q2:

Q3 (January-March 2015)
The priority in Q3 and Q4 is to work with communities on several different language Wikipedias to deploy Flow on pages and use cases where it can be helpful, and to focus on building features that will help active editors on those wikis to work together, and reach out to new contributors.

User-facing features:


 * ✅ A new model for indentation for discussion tangents (released, now evaluating the impact)
 * ✅ VisualEditor integration, with an editing toolbar (first version live, there will be more additions)
 * ✅ Category support for Topic pages
 * ✅ Editing other users' posts, with an Echo notification if your post is edited

Community partnerships
 * ✅ WP languages with Flow-enabled project pages (help, village pump): Catalan, French, Portuguese
 * ✅ WP languages with Flow test pages: Chinese, Hebrew, Punjabi, Russian, Telugu

Q4 (April-June 2015)
User-facing features:


 * ✅ Deleting and moving Flow boards
 * ✅ Page-width toggle, with Flow board header moved to the siderail
 * ✅ Mark-as-resolved feature
 * ✅ Edit patrolling
 * ❌ Search on a Flow board -- postponed until after Q2 2015-2016

Q1 2015 (July-Sept 2015)
User-facing features:
 * Opt-in for individual user talk page in beta features, on wikis that request it
 * ✅ Convert LiquidThreads pages to Flow on Mediawiki.org, other wikis that want to convert
 * Split Echo notifications into two icons -- Alerts and Messages

Q2 (Oct-Dec 2015)
Collaboration team will be working on:
 * Global Echo notifications, cross-wiki
 * Workflows, see the Collaboration team page for more information

Components of the discussion system
Here's a brief list of the main feature areas for a discussion system, a description of what the plan is for each one, notes about the status, and links to any ongoing discussions. It'll be regularly updated to factor in new discussions, and to note the permanency of the feature.

Is Flow replacing talk pages?
The Flow discussion features are being used successfully on user talk pages, help spaces and village pump-style group discussion pages.

There are other, more complex use cases for some wiki talk pages, which will be addressed as part of the Workflows project.

What wikis are using Flow?
As of December 2016, Flow is enabled on 25 wikis (see Flow/Rollout), some of them are using it as a beta feature on user talk pages. You can make a request to have Flow on your wiki (WMF wikis only). The technical process for rollout, is documented at Flow/Rollout#Process.

Can I opt out?
In terms of viewing, you won't be able to opt out of seeing Flow. If other users have converted their talk pages to Flow pages, or reached consensus that a Wikipedia or article talk page should be converted, there's not going to be a way to avoid using Flow if you want to contribute to that page.

What happens to current talk page discussions?
When Flow is enabled on an active wiki talk page, the existing dicussions are moved to an archive page. There's a link in the Flow board's side rail to the archive page. Old discussions aren't thrown away; we know how important discussions are to understanding the collaborative history of a wiki page or project.

We won't be able to "convert" wiki talk pages into the Flow format, because there isn't a clear one-to-one correspondence between a wiki talk page edit to a Flow post. It's more respectful to the discussions if we preserve the original format, on an archive page.

What about IP/anonymous editors?
Anonymous users are able to use Flow-enabled talk pages as any other user. However, subscriptions to individual topics, and notifications based on those subscriptions, will only be available to logged-in users.

Why don't we use a pre-built system, like PHPBB or Discourse?
On a wiki, the discussion system needs to connect to the rest of the wiki systems, including history pages, contributions pages and diffs. It would be harder to integrate a pre-built system than it is to build our own.

Why not use LiquidThreads?
LiquidThreads (LQT) was an early attempt at creating a structured discussion system. It has both strengths and weaknesses. After exploration and discussion, LQT was abandoned as a solution going forward for several reasons: poor performance, due to the way individual comments or posts are stored, parsed, rendered, cached, and assembled; no support for globally unique identifiers; and lack of flexibility with regards to workflows and collaboration techniques beyond simple discussion.

We have a conversion script that turns LQT discussions into Flow topics, which has now been used to convert all the LQT threads on MediaWiki.org into Flow. Details at Flow/Converting LiquidThreads.

How does Flow handle spam and vandalism?
In the current release (September 2015), each topic and individual post comes with a set of moderation features. These are:
 * 1) Hide (equivalent to reversion/rollback);
 * 2) Delete (equivalent to revision-deletion), and
 * 3) Suppress (equivalent to oversight or suppression)

Handling spam and vandalism in Flow should actually be easier than dealing with it on existing talkpages. Because Flow topics and comments exist as discrete elements, a specific post can be removed with a single set of actions: there's no need to go through the page history removing intervening comments, for example. In terms of spam, Flow is integrated with the AbuseFilter and the global and local Spam Blacklist. See mw:Extension:Flow/Moderation for technical details.

Does Flow support wikitext or VisualEditor?
Both. Flow is linked into Parsoid, which is the software that VisualEditor uses to read and write wikimarkup. Hooked into that is a wikitext editor and VisualEditor. Users are able to pick which they want to use, and the last edit-mode that is used to edit the content within, will be saved as a hidden preference. VisualEditor is used as the "preview" function.

Does Flow support all the templates and other markup we need in discussions?
Whatever markup Parsoid supports, Flow can support. Generally speaking, anything users commonly need to use (mathematical symbols, references, templates) can be added to a Flow post. You can see and test templates and other markup in the sandbox, e.g. this topic has some examples.

What happens to my custom signature?
Flow will not directly support custom signatures, for a couple of reasons.

The first is that they're disruptive from a UI point of view. Custom signatures are great for letting people know who said what; they allow for a specific user to be easily, visually distinguishable in discussions. The problem is that the way this comes about is by allowing refactoring of where links live, how they're displayed, and so on. As a result, there's a complete lack of consistency, which hurts the ability of users to navigate easily. One user might have their talkpage link in one place – another in a different place, and with a signature that doesn't actually reveal their username. The second is technical; allowing people to add raw HTML formatting into Flow boards could cause serious issues and errors in how the page is displayed.

Having said that, we appreciate the advantages of a custom signature; it allows for some visually distinguishing elements, and it allows for forms of identification that extend beyond username (e.g. in a second language). We're going to be working a "preferred name" field into the interface to allow for the latter; while it won't be as malleable as the status quo, it will allow for some originality. Your own posts will be visually highlighted to be more easily findable.

Can I edit other people's posts?
Yes. In the current release, autoconfirmed+ users are able to edit the posts of others, to fix problems or look at the wikitext. When you edit another person's post, there's a clear signal on the page that the message has been edited.

How will you support all of the processes Wikipedia uses?
It's a complex problem, which is why we started with the most basic process first – unstructured user-to-user discussion.

In October 2015 the Collaboration team postponed the Workflows project, which would handle the more complex talk page use cases.

If you are not working on Flow, will the visual editor be enabled on talk pages?
​No. This question comes up quite often.
 * The visual editor (VE) is designed to edit content, plain pages of text.
 * Talk pages aren't content. Many of the tools and design patterns that make VE nice to use to edit content make it poor to use for discussions. ​
 * To make it usable for discussions, we would have to remove or break many of those patterns in VE. We have spent a lot of time researching with users what works best there.
 * VE can't deal with structured discussions and plain-text discussions are not structured discussions.
 * Discussions like they are on traditional talk pages are not structured discussions from a technical perspective, despite the fact there is a certain number of colons or bullet points added to each answer to provide a pseudo-structure. With the current design of classical discussions, a piece of software can't know who has replied to whom – only humans can. There is no real connection between posts (which post is the parent/child of which), which is the definition of a structured discussion.
 * In Flow, each post is independent with a unique ID, linked to other posts and to a Topic (also with a unique ID), with a specific history, and all posts can be targeted precisely. It would be possible in the future to have conversations at multiple places, to move topics or replies, and to create sub-discussions with Flow. Classical talk pages, using VE or not, do not allow that.

I can't use any page on Flow. Why?
It is probably a compatibility problem. That page may help you.

Why do you use Topics and replies URLs that are not understandable by a human (like Topic:RdZ3SJY7W5Wtr)
These URLs are an unique ID. Flow has been designed to allow cross-pages and cross-wiki display which an unique ID. It is not possible to have multiple topics titled  Topic:Hello . A way to change topic names has been investigated to have something more explicit, like, but that still have that necessary unique ID somewhere.

Is there a way to all find pages that use Flow ?
For wikis using CirrusSearch this can be found using the "contentmodel" keyword, e.g. Special:Search/contentmodel:flow-board. This will only find flow pages, not the threads within them until they are cleanly separated (T73196).

Why is there so much whitespace/padding?
Whitespace is used for your eyes' resting spots. It helps you focus on content and increases content comprehension by 20%, which is important in discussing complicated issues. It decreases user dissatisfaction, which could result in an unhealthy discussion and harassment. We know what kind of harm to productive conversations misunderstandings and misinterpretation can do.

In addition to the above, white space helps structure a wall-sized amount of text, communicates the relationship between content, and improves scannability and readability. "The eye cannot focus on excessively close lines and … the reader expends energy in the wrong place and tires more easily. The same also holds true for lines that are too widely spaced ... Where reading is smooth and easy, the meaning content of the words is grasped more clearly[.]" The optimal text leading is x1.5 of the text size. The text size we will be using is 16pt at 25pt leading.

Why is there limited indenting/threading of comments?
Mobile readership is growing dramatically (currently, representing almost 1/4th of total pageviews to Wikipedia), so we need to build for a future where we have users who are purely mobile-only. Multiple indentations will have problems displaying on a small screen.

There are also many general usability arguments out there for why discussion systems that use indentation (also called nesting, branching, or threading) to indicate the relationship between comments are problematic. As Joel Spolsky writes: "Branching is very logical to a programmer's mind but it doesn't correspond to the way conversations take place in the real world. Branched discussions are disjointed to follow and distracting. (...) Branching makes discussions get off track, and reading a thread that is branched is discombobulating and unnatural. Better to force people to start a new topic if they want to get off topic."

We want to structure conversations in a way that makes sense and fosters a healthy discussion. The framework we're proposing places more emphasis on discussing the topic and less on tangents. (Users can still engage in tangents with one another, but the primary action that is emphasized is responding to the topic.) To complement this system, we are planning to add the ability to easily split tangents off into new topics, since it's likely that long tangents are, in fact, different discussions altogether. What we want to de-emphasize (without entirely disabling) are long back-and-forth tangents between two users that have no relation to the main topic. This is usually the hallmark of an unhealthy conversation or just one that needs to be moved off to a new discussion.

Why are we using big colored buttons?
The buttons in Flow are part of OOui (previously from Agora), a new standardized UI library for Wikimedia projects. We use colored buttons to emphasize what to click next in order to complete a particular workflow. The blue-colored button signifies a progressive action that requires more steps ahead, while a green-colored button signifies the final progressive action. Links are used in areas where the action is not necessarily encouraged or discouraged (e.g., replying to any specific post).

Are you working on a design without JavaScript, for users with accessibility or browser concerns?
Yes, we aim to make most of the core Flow functionality work without JavaScript, on older browsers, etc. The software will work, but it will not work optimally. Also, given the nature of the way Flow is designed to behave, disabling JavaScript "for performance reasons" may actually create poorer performance than with JavaScript. For example, Flow will make use of a technology called lazy loading that will reduce immediate request overhead for browsers that have JavaScript enabled. This will have the effect of causing the pages to appear to load faster than the non-JavaScript version, which will require all elements to load before achieving full functionality. Replying to a post with JavaScript enabled will be done in-line and quickly, in the background, while replying without JavaScript will require loading a new page, submitting the reply, and then reloading the discussion.

Why is there gray text?
Pure black text is harsher for the eye to read on a white background, due to strong color contrast. Text will start to flicker, users will experience eye fatigue and strain, and they will be tempted to stop reading. If my eyes gives me a limited amount of time to read and try to understand a discussion thread, especially a complicated one, I'm more likely to get frustrated and give up. That's not a good user experience. The benchmark of text color on white backgrounds to avoid these issues is #333.

Why does it look like Facebook/Twitter/StackExchange, etc.?
The Wikipedia community has very different values from many of the other popular discussion websites. But the important thing to remember is that those sites have done lots of elaborate user research and A/B testing to find what works best for facilitating discussions, reducing flame-wars, and creating inviting and easy-to-use interactions. We don't want to reinvent the wheel when it comes to the basics of online discussion, and we don't want to create something that breaks most Internet users' expectations of what a discussion system looks and behaves like. Flow should be intuitive enough for anyone to use without having to read a manual, and that means following the best practices of discussion interface design.

However, we are aware that the discussion system on Wikipedia is more than just a tool for communication, but also a medium for collaboration and consensus-based decision-making. We are going to keep iterating and responding to your feedback on how to better serve those usages.

In addition to the sites you may be familiar with, here are some other sites we look to for inspiration/guidance that have structured discussion systems:


 * YouTube
 * Flickr
 * PhpBB
 * Simple Machines Forum
 * 1) Gawker
 * 2) Discourse
 * 3) Gizmodo
 * 4) StackOverflow
 * 5) Medium
 * 6) Quora
 * Tumblr
 * 1) The Verge
 * 2) Reddit
 * Livejournal

If there are patterns from these sites that you think might be interesting to explore on Wikipedia – or if there are patterns you feel do not belong in a Wikipedia discussion! – please let us know.

Why are we using this Topic and Post order?
The default order in the current release is: new topics appear at the top of the page, and new posts within those topics appear at the bottom, below older posts. There is also a sorting feature that allows users to see the most recently active topics at the top.

Infinite scroll, and the elimination of the need to archive - this aspect necessitates top-posting.
 * Topic order:

More intuitive for newcomers and more efficient for seeing new/updated content. New/updated topics appearing at the top follows standard set by many forums, social media, and email.

Replies to topics appearing oldest to newest (top to bottom) make sense as a way of encouraging users to read through the existing conversation before jumping in to comment.
 * Post order:

Development principles
With any complex software project, it's almost impossible for the designers, developers and product people to know everything. This is a particular problem in an environment like that of the Wikimedia projects - due to the sandbox-like nature of the place, there are tens of thousands of different workflows, different user needs, and different problems. Even if we could accurately identify all of them, we can't necessarily tell if our solution is the right one until we put it in front of users.

Accordingly, we're keeping two things in mind while we're developing the Flow software. First: we are partners with the community on this. Editors are welcome and encouraged to participate in the development process, pointing out things we've missed, identifying and describing new workflows, and helping keep us honest - when something hits this level of complexity, it's impossible to make things work without as many people helping as possible. Before and after we build things, we'll open a conversation about the feature. Second: a lot of the work we're going to do, at least initially, is experimental: we don't know if it's the right implementation of a feature. If it's not, we'll be happy to roll it back.

Who's working on Flow?
See: Collaboration/Team

Contact and links

 * IRC channel:
 * Wikitech mailing list
 * Phabricator:
 * Collaboration team (the primary task management locations): Current, Backlog
 * Flow: open tasks, all tasks, submit new task