Structured Discussions


 * For information on how to install and use the Structured Discussions extension, see Extension:StructuredDiscussions.

Structured Discussions is a project of the Global Collaboration team at the Wikimedia Foundation to build a modern discussion system for Wikimedia projects. Structured Discussions provides features that are present on most modern websites, but which are not possible to implement in wikitext. For example, Structured Discussions can show readable threads on mobile as well as desktop, automatically signs posts, threads replies (with an in-database relation between each), and permits per-topic notifications.

The main goals for the Structured Discussions project are: Structured Discussions has been deployed on user talk and wiki-wide discussion pages on various languages in the Wikimedia content projects, as well as on Mediawiki.org – see Structured Discussions/Rollout. On some wikis, it is available as an opt-in Beta feature, allowing users to turn on Structured Discussions for their own user talk page – see Structured Discussions/Request Structured Discussions on a page.
 * 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

Structured Discussion was formerly known as “Flow”. Flow was a bigger project that has been re-scoped to focus on user-to-user discussions. The software has been renamed to reflect this change.

History
After the initial development round, Flow has been in active maintenance mode, with no major development since mid-2015; no significant new features have been added since then. The team continued to support the product and fix bugs and to make sure that people who were using Flow continue to have a good experience.

The Collaboration Team remained interested in the project and in providing an improved system for structured discussions. Communities have also expressed interest, by requesting Flow for testing or for real-cases use. To make decisions about the way forward in this area and future developments, a survey was sent to many Flow users in September 2016; the results were published in February 2017. Those results have been used to make the Wikimedia Foundation’s plans.

Structured Discussions improvements are a goal of the 2017-2018 Fiscal Year development plan, focusing on search and interactions between topics.

Development status
The following schedule is indicative. These tasks may improve other Structured discussions features.

July–September 2017

 * Rename the software - interface, repos, files; not databases. (T174137)
 * New topics and posts on structured discussions will have wiki text storage instead of HTML (T174374)

October–December 2017

 * Front-end rewrite to use OOjs UI – no significant changes in design. (T100269)
 * Search on Structured Discussions
 * On-page (board) search (T76823 and T106767)
 * Wiki search integration  (T62493)

January–March 2018

 * Move topics from one board to another. (T88140)
 * Move comments within a topic. (T95118)
 * Filter topics on-page for "don't show me discussions marked as Resolved" (T76823)
 * Human-readable topic URLs (T59154)

April–June 2018

 * Overflow for work above.

Deployments
Structured Discussions are available on certain wikis. Those wikis will automatically get the new features and improvements.

Wikimedia wikis that don’t have a Structured Discussions board enabled will not have Structured Discussions activated, unless they request to activate Structured Discussions. This request is only possible if they have reached a consensus.

Components of the current discussion system
You can have a look at the quick tour to discover the most important features.

Overall design

 * Design density: readability is improved and eye-fatigue is diminished by a more airy design
 * Topic order: topics are displayed from last-added to first-added, like it is on most discussion systems on the Web.
 * Message separation: different messages in the same thread will be visually distinguished through design cues.
 * Navigation and archiving: the software features infinite scrolling on a Structured Discussions board, with all of the discussions accessible on the same page. A Table of Contents in the side rail to help users navigate quickly between topics on a board.

Notifications and interactions

 * Topic namespace and links to replies: each topic is a separate page and every message has its own link to ease quoting.
 * Notifications: a set of notifications ease topic watching. Users are notified when a new message is created on a page they watch, or if a reply is posted on a topic they watch. Notifications link directly to the messages.

Add or edit messages

 * Input method: the visual editor and wikitext editors are equal input methods, users can switch back and forth at anytime.
 * Threading: Messages are posted below the oldest one and don’t require editing a whole section. There is no need to know the threading system using wikitext, reply buttons provide two sets of indentations for digressions.


 * Auto signature: each message is automatically signed and timestamped.


 * Editing messages: each message can be edited (depending on user’s rights) without editing the whole section of messages. If someone other than the original author edits a comment, that fact is highlighted.
 * Mention users: mentioning is eased by a mini-search system.

Message moderation

 * "Hide", "Delete" and "Suppress" - analogous to revert, revision-deletion and oversight - are available on Structured Discussion. Users also need the ability to delete/suppress entire threads.
 * Since threads can potentially exist on multiple discussion pages, a protection system that is equitable to users is difficult to get just right.
 * User links automatically include links to their contributions and block links, to help sysops deal with disruption quickly and effectively.

Is Structured Discussions replacing talk pages?
The Structured Discussions 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 may be addressed in a future "Workflows" project.

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

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

What happens to current talk page discussions?
When Structured Discussions is enabled on an active wiki talk page, the existing discussions are moved to an archive page. There's a link in the Structured Discussions 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 Structured Discussions format, because there isn't a clear one-to-one correspondence between a wiki talk page edit to a Structured Discussions 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 Structured Discussions-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 Structured Discussions topics, which was used to convert all the LQT threads on MediaWiki.org into Structured Discussions. Details at Flow/Converting LiquidThreads.

How does Structured Discussions 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 Structured Discussions should actually be easier than dealing with it on existing talkpages. Because Structured Discussions 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, Structured Discussions is integrated with the AbuseFilter and the global and local Spam Blacklist. See mw:Extension:Flow/Moderation for technical details.

Does Structured Discussions support wikitext or VisualEditor?
Both. Structured Discussions 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 Structured Discussions support all the templates and other markup we need in discussions?
Whatever markup Parsoid supports, Structured Discussions can support. Generally speaking, anything users commonly need to use (mathematical symbols, references, templates) can be added to a Structured Discussions 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?
Structured Discussions 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 Structured Discussions 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.

Instead or in parallel of Structured Discussions, 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 encyclopedic 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.
 * Discussions like they are on traditional talk pages may contain unstructured parts, although there is a certain number of colons or bullet points added to each answer to provide a lightweight structure. With the current design of classical discussions, a piece of software can't know who has replied to whom – only humans can.
 * In Structured Discussions, 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 Structured Discussions. Classical talk pages, using VE or not, do not currently have that feature, and adding it might prove cumbersome.

I can't use any page on Structured Discussions. Why?
It is probably a compatibility problem; see Structured Discussions/Known problems.

Why do you use Topics and replies URLs that are not understandable by a human (like Topic:RdZ3SJY7W5Wtr)
These URLs are an unique ID. Structured Discussions was designed to allow cross-pages and cross-wiki display which have a unique ID. It is not possible to have multiple topics titled  Topic:Hello . A way to change topic names was 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 Structured Discussions ?
For wikis using CirrusSearch this can be found using the "contentmodel" keyword, e.g. Special:Search/contentmodel:flow-board. This will only find Structured Discussions 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 used for Structured Discussions is 16pt at 25pt leading.

That being said -- there is a wide range in users' preference for information density. Core MediaWiki is very information-dense, with a completely fluid width and tight line spacing -- and, possibly not coincidentally, experienced MediaWiki users tend to prefer greater information density. (This may be the equivalent of natural selection.) One of the goals for Structured Discussions is to make the discussion system more accessible for new users, and part of that may include a less info-dense design. We're still figuring out the right balance, and this may include individual preferences for display density, with Gmail's 2013 redesign as an example.

See the following for more discussion and analysis of whitespace and font sizes on the web:
 * Whitespace myth
 * Best practices analysis

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 Structured Discussions 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?
The aim is to make most of the core Structured Discussions 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 Structured Discussions is designed to behave, disabling JavaScript "for performance reasons" may actually create poorer performance than with JavaScript. For example, the plan is for Structured Discussions to 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. Structured Discussions 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 Structured Discussions 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 Structured Discussions?
The Global Collaboration team. Product manager is James Forrester.

Contact and links

 * IRC channel:
 * Phabricator:
 * Collaboration team (the primary task management locations): Current, Backlog
 * Structured Discussions (as Flow): open tasks, all tasks, submit new task