Flow/Use cases

This document sets out the most prominent use cases in discussion-based namespaces, and the technical developments in Flow necessary to enable them (or enable a like-for-like replacement).

Premise

Flow was developed by the Wikimedia Foundation aiming to replace current discussion pages - largely, although not entirely, conducted in the Talk: namespaces - with a structured and granular discussion system. Talk: pages (talkpages) as they are at the moment are identical to any other wiki page - essentially a large sandbox. The freedom and deficiencies granted by this system have led to a large number of user-generated workflows, on a large number of wikis, around specific tasks such as blocking or unblocking. This is both a boon and a hindrance to Flow - a boon because we can, by looking at these workflows, see how people use talkpages in practise, but a hindrance because we have to adapt Flow to meet these requirements.

To examine these workflows, both the hindering and aiding elements, a sample of edits was taken from the recentchanges table on enwiki. These edits matched the following conditions:

1. They were to the talk, user talk, wikipedia or wikipedia talk namespaces;
2. They were edits to an existing page, rather than log entries or actions that created a page;
3. The length of the page following the edit was greater than the length prior to the edit - the edit added content.

Of these edits, a randomised, normalised sample of 500 edits was taken from each namespace, with each edit formatted as a diff and exported in a TSV. This was then manually hand-coded by myself and User:Thehelpfulone. From these hand-codings, graphs were produced showing the types of pages in each namespace, and the types of action taken in relation to each page. Available are the TSV itself, the script used to retrieve and normalise the sample, and the script used to produce the graph.

Hand-coding was done on the following basis; that what different pages are, or what different actions are, are not our concern. The fact that a user might leave an RfC notice or a dispute resolution notice is irrelevant; what is relevant is that in both cases users are leaving a semi-automated notification of action elsewhere, and that these notifications need to be supported by flow. What matters is not the format of the message, it's how the message is implemented and what parts of a talkpage's structure it depends on. Accordingly, we primarily investigated implementation and structure rather than content; this is listed as the Coding. At the same time, different pages and types of page have different purposes, which themselves have an impact on structure: an AfD's requirements and format is very different from that for a noticeboard, which itself differs from that of a content review. Types of pages were also coded, and are listed as PageType.

Talk namespace

Codings

Codings

"Archive boxes", used to link through to talkpage archives. Two different designs are visible, highlighted in blue.

1. RfCs, or Requests for Comment. A Request for Comment is a structured discussion that seeks community feedback on a particular issue: in the "talk" namespace the issue is usually the content of an article. While RfCs are a relatively uncommon use case, they are highly important to how the community functions and resolves disputes, which means that finding some way of taking them into account is crucial.

   RfCs are denoted, on enwiki, by the presence of a template at the top of the thread - usually Template:Rfc. This indicates to various transcluding and tracking bots that the RfC exists and is live, and enables its inclusion in particular categories. Such functionality is probably not something that Flow can replicate, and this type of metadata is used in closing the RfC, too (see below). One possible way around it would be permitting a "metadata" space at the top of each Flow thread.

   RfCs consist of several components that distinguish them from regular discussion. The first is that they usually have an implicit or explicit expiry date, which is commonly 30 days on enwiki but may be different elsewhere. In other words, they must be exempt from Flow's normal archiving process - insofar as they must persist for a set time period, even if that is longer than the page's normal archiving rate, and be able to be archived on request.

   The second is that they are closed; an administrator, usually, is tasked with shutting the discussion and reaching a particular conclusion. Closing consists of removing or modifying the RfC tag to denote its closed status (and also, in some cases, whether the discussion closed in support or opposition of the initial proposal, of there was one), and adding a rationale for the decision that was reached. This is something else that could be solved for with a 'metadata' section.

   They can also consist of multiple threads - threads which have to exist as part of a single whole. If Flow is treating level 3 headers (and the equivalents) as subsidiary elements of the associated level 2 header, this is, of course, solved for.

2. Redirects are commonly found in the Talk: namespace; they usually result from the move of a page (and its talkpage) to new page titles: the old page titles are turned into redirects so that readers can easily find the content. This highlights two problems that Flow will have to tackle - how to handle moves of the 'anchor' board that threads are associated with (or the page that board is associated with), and how to treat the talkpages of redirects in any migration to Flow. One way of handling the second problem would be simply to identify if a page in the Talk: namespace is a redirect, and not initialise a flow board there.
3. By metadata we mean things such as wikiproject tags - templates at the top of the talkpage that indicate those Wikiprojects the article falls under, and how those projects grade the article in terms of quality and importance.

   This sort of metadata - other examples would be media coverage of the article - has absolutely nothing to do with the process of discussion itself; it lives on the talkpage because there is nowhere else for it to go, and it is generally useful to have around. This is a good example of a use case for talkpages that Flow has to take into account; the inclusion of metadata about the associated article. Any Flow deployment will need to either include these elements in Flow-enabled pages, or find a better way of representing them.

   Other types of metadata are pertinent to actual communication; an example is the talk header template, which contains guidance on how to use talkpages and what standards are expected of discussion participants. This is, broadly-speaking, useful to have around; having a way of representing it in Flow, in a way associated with the actual discussion, could be very important. At the same time, this sort of template is unnecessarily wordy and stylised; it may be more useful to create a 'metadata' space at the top of each Flow thread, similar to the concepts of page notices or edit notices, that can be filled with this sort of thing (or anything else!) automatically.

4. The most prominent coding in the Talk namespace, unsuprisingly, is discussion, such as this edit. This consists merely of conversations - structured or unstructured - occurring in wikimarkup on talkpages. Given that this is a primary use case for Flow, its elements do not need to be elaborated on at length.
5. Drafting is an essential process taking place at talk pages. Users create versions of sections to discuss, often copying and pasting contents from wiki articles, and refine and create alternatives interleaved with discussion. When a final version is agreed upon, it is pasted into its final place at Article space.
6. bot signing. At the moment, because of the structure of talkpages (or rather, the lack of structure), users must manually sign each post that they make. A set of bots (most prominently SineBot) are tasked with signing posts when users forget. This, like discussion, is something that is integral to Flow, and so isn't something that really has to be considered - having a built-in way of identifying who wrote each post is prima facie a feature.
7. Last is archiving. Archiving does what it says on the tin; it takes a set of talkpage threads and archives them on a subsidiary page. Theoretically this is also part of Flow's core requirements - but the problem of how to refer back to talkpage archives under the "old" system means that investigating what these archives look like is quite important.

   Archiving can be done in a number of ways; automatically, by a variety of bots (such as MiszaBot), or manually. Each type looks very different. With automatic archiving, threads that meet certain parameters - not contributed to in the previous 30 days, for example - are removed from the talkpage and copied wholesale to a subsidiary page. These pages remain static, and are usually referred to via a template containing links to each archive, as seen in the screenshot to the right. One way of handling these would be to simply include some way of referring to the old pages, such as these templates, in the "metadata" section covered by point 2.

   Archiving can also be done manually, which is more difficult. This can range from simply manually replicating the bot functionality - cutting-and-pasting content from a talkpage to a subsidiary page, and including a link to the subsidiary page on the talkpage - to merely blanking the content, so that it remains in the page history, to deleting the revisions and moving them to a subsidiary page in order to preserve attribution.

   Dealing with all possible ways of archiving is going to be difficult. One possible way of doing it, albeit, one that would force us to abandon those that have been deleted and moved, would be to write a simple parser to identify section headers in the page history and, every N headers, create a new (subsidiary) page under a single common set of naming parameters that can be identified by Flow. These pages could then be included in the Flow archive box, however that's going to be built.

PageType

PageType

The talk namespace has, unsuprisingly, relatively few types of page. PageType is important if we're talking about automatically converting pages into Flow boards, or replacing them with Flow boards, since we don't want to overwrite something that isn't meant to be a discussion. PageTypes include:

1. Talk pages, shockingly. This is the main use case for Flow, and consists of the elements described in Codings.
2. Article reviews and evaluations, coded as GANs. These are pages that exist as a sandbox for peer reviewing an article's content; much like metadata, they have nothing to do with actual many-to-many discussion, but exist in the talk namespace because of difficulties effectively storing them elsewhere. While discussion does occur in article reviews, it's an individual user responding to another, individual user's concerns, such as here. One way of neatly sidestepping this issue would be to simply only convert talkpages immediately associated with an actual article, and not those that exist as sub-pages of a talkpage.
3. Archives. These are static pages that exist to document previous conversations, and are created by one of several methods (as discussed in "Codings"). Again, these should not be Flow-enabled; again, this can be handled by not enabling Flow for sub-pages.

User talk namespace

Codings

Codings

User talkpages are Flow's primary use case, and are also the most complex area in terms of the number of codings and possible uses.

1. YGM, or "You've Got Mail" messages, inform users that another user has sent them a message via Special:EmailUser. These are manually-posted templates; support for them need be nothing more than support for templates. At the same time, this is the sort of thing it would be nice to build into Echo (indeed, it's a perfect example of how the software should be used).
2. Welcomes are messages sent to invite newcomers to contribute in a specific field, thank them for their contributions so far, point them to places where they can get assistance, or any permutation of the above. These are mostly posted semi-automatically, on enwiki, through tools such as Twinkle or Huggle, and templated. The same is most likely true on other projects - and those that aren't, are sent manually and should fit within Flow's default workflow, so again it's largely down to API and template support.
3. Warnings. Warnings are messages cautioning users against particular kinds of negative action (vandalism, personal attacks, et al), and are not really discussion prompts in the traditional sense, although sometimes they do set off discussion. Instead, they are nothing more than notices of an action being taken (vandalism) and a reaction from the community (a revert). This is really something that should be handled by a notifications system, and Echo does send notices when reverts occur, but they can't really include the detail necessary to be a workable replacement for warnings. Instead, it's Flow's problem.

   Warnings are almost always templated, and mostly dispensed by semi-automated tools such as Twinkle and Huggle. In addition, several bots send out warnings, most prominently ClueBot. Because such tools are responsible for the vast majority of this kind of action (and there are a lot of warnings given), it's going to be important to involve their maintainers in the conversation about Flow and how they can hook into it. Many of these tools (such as Huggle) hook into the API to send messages - while having API access to Flow boards is a given, we need to make sure to socialise and document it properly in our developer community.

   Warnings can probably be treated just as we would any first message in a Flow thread, be they automated or manual; things are likely to become far more complex, however, when the VisualEditor is integrated given its difficulties dealing with templated messaging.

4. Talkback messages are messages letting a user know that a second user, who they're in conversation with, has replied to the conversation on the second user's talkpage. This is a legacy of MediaWiki's treatment of discussion boards as discrete and static pages, which led to the creation of two distinct workflows - the alternating workflow, in which users would converse by leaving user1's messages on user2's talkpage and vice versa, and the unifying workflow, in which messages would all be centralised in one thread on one talkpage. This is a primary use-case for Flow, and does not require additional support.
5. Tags are things such as bot notifications of disambiguation links or other automated messages, such as Page Curation notices that an article has been reviewed. These are not necessarily intended to to promote conversation (and, indeed, Echo has superseded manual notifications in some small areas) but are, realistically, too detailed to be handled through pop-out notifications. They have to be handled through Flow. In display and formatting terms, they can safely be treated as discussion - when it comes to how tags are posted, work will require both API support (many are handled via bots) and also changes to the PageTriage extension.
6. Newsletters are another example of something that acts as a notification, rather than as a prompt for discussion, but that Flow will have to support due to deficiencies in Echo. Examples are the military history Wikiproject newsletter and meetups, in both cases delivered automatically using EdwardsBot (as most newsletters are). This is another example of something that will require full API documentation and template support.
7. NA coded items are items that do not fit into any of the above categories. The most prominent example is newcomers misunderstanding talk pages, quite rightly, and treating it as another sandbox where articles or content can be placed. This is not a wanted use case, and so not something that Flow should support - indeed, by its very existence Flow should prevent a lot of these sorts of issues.
8. Help requests are requests for help from an experienced user, usually handled via templates, such as here.

   The workflow for help requests is fairly simple. A user posts a template on their talkpage, and postfixes it with a question or plea for assistance. The template automatically lists the talkpage in a category, and users looking for people to help go there and follow the link to the request. Once the request is answered, the answerer adds a parameter to the template confirming it's been dealt with.

   Theoretically, all we need to do to support this is allow for templates. However, much like blocking, this might be an area where a specific module could be useful. The steps would be very simple; write up a message, tag it as a message that contains a help request, and have it listed on either a centralised flow board or a category. Users who have answered the request de-tag the original post, or add a second tag overriding it.

9. Discussion notifications are notifications that the user is wanted to participate in a discussion. This could be an RfC, a discussion on a noticeboard somewhere, or anything else - the point of the message is to direct the recipient to a conversation elsewhere. On the face of it, this should be handled fairly similarly to deletion notifications, both automated and manual - API documentation and the normal functioning of Flow will be enough for it to work. Alternately, if we're planning to Flow-enable deletion discussions and other discussions, we could include a feature to notify users, through Echo, that their attention is wanted at this thread. Such a feature would achieve precisely the same thing as this kind of notification, but be far neater and cleaner, reserving the Flow boards for actual conversations.
10. Deletion notifications are notifications that a page the recipient is related to (the creator of, or editor of, for example) has been nominated for deletion. This is not intended to prompt discussion at the message, but instead acts as both a notification and a prompt to participate in discussion elsewhere - usually at Articles for Deletion or some similar page. Deletion notifications are sent in a mostly semi-automated fashion, by the tools that have already been discussed for "warnings"; again, API documentation is key. Alternately, we could look into finding some way to use a combination of Echo and Flow to notify users, as discussed under the next bullet point.
11. Blocking is an action taken by an administrator to prohibit a user from editing. It can be for a fixed time period, or indefinite, and while it doesn't directly show up on the talkpage administrators are encouraged to leave users a notification. At the moment this is handled by leaving a small template, automatically or manually, that informs a user why they are blocked and for how long.

    Blocking is logically followed by unblock requests, which are also referenced within the blocking template. To request an unblock, users (on enwiki, at least) reply to the blocking template with a new template they fill out, which includes an explanation of why they feel they should be unblocked. This template then adds their talkpage to a category and a summary of users requesting unblocks. Administrators then review the requests, and edit the template to either approve the unblock or deny it. Examples of both a request and a 'declined' request can be seen here.

    Supporting this, as it exists now, will not really require any additional effort - with proper API documentation and permitting templates on talkpages, we can simply replicate the existing functionality. This may, however, be an area where we want to spend time building a Flow module solely for this sort of request. If we do, there are several essential elements of the workflow; a specific type of 'block' section, a request for an unblock that allows space for a rationale, and the ability of administrators to then close such a thread with a particular outcome. Project-specific elements (categories or pages where the request is listed, for example) could be scripted using the workflow language we are discussing.

12. Awards are another type of edit. These can consist of anything from "barnstars" to Wikiproject-specific awards, and are awarded both automatically and manually. Nothing, other than allowing for template syntax, needs to be done to take manual awards into account - for automatically granted awards, which usually come from the WikiLove extension, we once again come back to having properly built internal and external APIs.
13. AfC messages are messages about the Articles for Creation workflow. These are essentially the same as discussion notifications - they inform the user that a decision has been made in regards to an article they have submitted, and point them to that decision. These are usually posted using a custom JS script; again, this will require outreach to our volunteer developer community.
14. Metadata refers to and requires similar things to metadata in the Talk namespace - support for templates in a standardised box that lives at the top of Flow boards, and in some cases, threads.
15. Discussion, Bot signing and Archiving, again: same requirements as the codings in the talk namespace.

PageType

PageType

1. User talk pages are the standard model for Flow
2. Archives are, well, archives, and follow the same patterns as with the Talk namespace.

Wikipedia namespace

Codings

Codings

1. Transclusion is a prominent coding not found in the talk or user talk namespaces (or, found very rarely). It refers to the practise of (and ability to) include the contents of one page in a second page, by including a reference to the first page in the wikimarkup of the second (using the format {{firstpagename}}.

   A common use case for transclusion is XfD (discussed more below) - deletion discussions. Each deletion discussion exists as a distinct page, with discussions aggregated by start date on centralised pages for ease of browsing. This aggregation is performed by transcluding each individual discussion into the aggregate page. This workflow is necessary because there are two objectives of an XfD-based system: to allow for easy identifying of XfD discussions, and to allow participation in individual discussions without having to engage with a vast amount of data. Storing discussions on discrete pages enables the latter; transcluding them together enables the former. This is also the reasoning behind the other prominent use case for transclusion - the featured process.

   Flow's format - distinct threads, anchored to a single board (or multiple boards!) should effectively give us the benefits of transclusion anyway; this isn't something we need to directly take into account, except when it comes to implementing Flow for things like XfD discussions or similar things.

2. Signing is self-explanatory; bot signing, but manually done by other users.
3. Relisting refers to an XfD-specific feature to extend a discussion past its normal closing date. XfDs are normally closed after seven days; in the event of poor levels of participation, admins can choose to extend this to 14 or 21 days. In practise, this is not introducing a new requirement; it simply requires an ability to close discussions and control over archiving dates, both of which are noticed as compulsory features for other use cases.
4. In-title metadata is metadata found in section headings, such as here. Ultimately, whatever is trying to be communicated with it can also be communicated through metadata stored below that - having those noticeboards that use this convert to that system sounds far easier than supporting endless permutations of this use case.
5. NA: things, as usual, outside the scope of Flow, i.e. the use of the Wikipedia namespace for non-discussion types of action. An example would be contributions to the 'requested articles' page.
6. Discussion notifications refer to, essentially, the same thing as with the User talk: namespace, and will require the same Flow features.
7. Metadata, Discussion, Bot signing and archiving, ibid.

PageType

PageType

1. XfD are briefly discussed above, and refer to deletion discussions of various types. All of them have two things in common; they're discussion-based venues, and they're a major domain of activity that Flow could (potentially) apply to. These discussions are handled in several different ways, but with some common threads:

   They feature voting. This voting normally includes large rationales, and if necessary can be treated as discussion. However, it is a common enough use-case (as we'll see) to potentially be treated as something worth a workflow module.

   They involve the transclusion of pages in some cases, and multiple threads statically tied to a single board in others. In both cases, they need space for metadata at the top of each board and the top of each thread.

   They are closed and marked as inactive after a set period - but are marked as such by an admin. For Flow to be enabled on XfDs, we need a way of controlling archiving timings on a thread-by-thread (or board-by-board) basis, and a way of closing threads.

2. Teahouse: the Teahouse is a project by Siko Bourtese's team to create a decent discussion venue for newcomer questions. The structure is closer to a traditional forum than to a talkpage - the most noticeable attributes are custom formatting and top-posting. To support the teahouse, we need metadata support, but we will also need a decent way of customising the order in which posts display. The posting order (and the teahouse itself) is not big enough for this to be a necessary component of any Minimum viable product (MVP), however.
3. Requests for Comment, covered above, are community-wide discussions of particular issues or users. In the Wikipedia namespace, these take the form of discrete pages entirely dedicated to the subject-matter, such as this one. The format includes both discussion and non-discussion elements, but it is a fairly prominent discussion venue; components and requirements include voting and metadata capabilities, as well as the ability for a discussion to be closed. If these are going to exist as discrete boards, there must also be an ability to disable archiving of threads completely on a per-board basis.
4. RfA - Requests for Adminship. These have a strong voting component, and also requirements for transclusion to a centralised page and disabled thread archiving, along with a closing component.
5. Noticeboard - the main home of discussions in the Wikipedia namespace, noticeboards are normally organised around topic area. Prominent noticeboards include the reference desks and AN/I. Largely, noticeboards feature mere discussion, but there are a lot of pages that include metadata, such as the reference boxes at the top of AN/I, and there is sometimes a strong voting component. Indeed, given the varying ways voting is used, if we do implement something vote-based it's probably best to be able to enable it on a thread-by-thread basis.
6. NA - uses of the Wikipedia namespace for things that are not discussions.

Wikipedia talk namespace

Codings

Codings

1. The Wikipedia talk: namespace is relatively infrequently used, and use cases are limited. The pertinent ones are already covered, as are the technical requirements they'll have: signing, discussion, metadata, archiving and discussion closing.

PageType

PageType

1. Talkpages are just that - talkpages. While the Wikipedia namespace contains many types of page, almost all of those we are concerned about fall into the simple format of discussion pages - albeit pages that discuss governance, rather than content.
2. NA refers to the use of the Wikipedia talk namespace for things other than discussion. A prominent example is Articles for Creation. These need not concern us, except to note that the complete conversion of this namespace to working through Flow is improbable and would be a detriment.

Reference tables

Codings

Namespace	Coding	MVP	Utopian solution
Talk:	RfCs	Space for metadata Exceptions to rules around automatic archiving Ability to mark as closed	Voting module/closing module, plus all of the MVP
	Redirects	Way of handle moves of pages with an associated Flow board Not initialising Flow boards on redirects/on talkpages of redirects	NA
	Metadata	Spaces for metadata at the top of each Flow board Ditto, in many cases, at the top of each thread Support for template syntax within Flow posts	NA
	Discussion	NA - primary use case	NA - primary use case
	Bot signing	NA - primary use case	NA - primary use case
	Archiving	Automated archiving of non-Flow posts on now-Flow-enabled pages following a common naming system	The same, but with a prominent link to non-Flow archives built into Flow boards.
User talk:	YGM	Template support	Echo notification for use of Special:EmailUser
	Welcomes	API support Template support Discussion with volunteer devs	NA
	Warnings	ibid.	NA
	Talkback	NA - primary use case	NA - primary use case
	Tags	API support Discussion with volunteer devs PageTriage alterations	NA
	Newsletters	API support Discussion with volunteer devs	NA
	Help requests	Template support	Help request module
	Discussion notifications	NA	Notify users, through Echo
	Deletion notifications	API support Discussion with volunteer devs PageTriage alterations	Ibid.
	Blocking	API support Discussion with volunteer devs	Block/unblock module
	Awards	API support Discussion with volunteer devs Template support WikiLove alterations	Example
	AfC	API support Discussion with volunteer devs	Example
	Metadata	Spaces for metadata at the top of each Flow board Ditto, in many cases, at the top of each thread Support for template syntax within Flow posts	Example
	Discussion	NA - primary use case	NA - primary use case
	Bot signing	NA - primary use case	NA - primary use case
	Archiving	NA - primary use case	NA - primary use case
Wikipedia:	Transclusion	NA - primary use case	NA - primary use case
	Signing	NA - primary use case	NA - primary use case
	Relisting	Exceptions to rules around automatic archiving Ability to mark as closed	NA
	In-title metadata	See "metadata" above	NA
	Discussion notifications	See "Discussion notifications" in "User talk:"	NA
	Metadata	See "metadata" above	NA
	Discussion	NA - primary use case	NA - primary use case
	Bot signing	NA - primary use case	NA - primary use case
	Archiving	NA - primary use case	NA - primary use case
Wikipedia talk:	Transclusion	NA - primary use case	NA - primary use case
	Discussion	NA - primary use case	NA - primary use case
	Bot signing	NA - primary use case	NA - primary use case
	Archiving	NA - primary use case	NA - primary use case
	Signing	NA - primary use case	NA - primary use case
	Metadata	See "metadata" above	NA

PageType

Namespace	PageType	Codings/requirements
Talk:	Talk pages	Metadata Bot signing RfCs Discussion Archiving
	Article reviews and evaluations	Rules around automatic deployment of Flow
	Archives	Rules around automatic deployment of flow Archiving
User talk:	Talk pages	All pertinent codings
	Archives	Rules around automatic deployment of flow Archiving
Wikipedia:	XfD	Voting module Metadata Relisting
	Requests for Comment	Voting module Metadata Closing Archiving controls
	RfA	Voting module Archiving controls Closing
	Noticeboard	Discussion Voting module Metadata Archiving controls
Wikipedia talk:	Talkpages	Metadata Bot signing RfCs Discussion Archiving Archiving controls Discussion closing