Flow/Functional Specifications/Boards and Topics

This document describes a set of functional requirements regarding the user experience for the threaded discussion system for Flow This document concerns itself with the behavior of Boards and Topics exclusively. Posts are handled in a different document.

This document should not be taken as a final descriptor for any one specific release of the software, though recommendations regarding inclusion in the "Minimum Viable Product".

Board: A board is a group of subjects. A talk page converted to Structured Discussions is a board. There is only one board per page.
Description: Content on the right column of a Board (introductory text, templates, and similar). Category links in here, will add the Board to the category.
Topic: A topic is a structured discussion about one particular subject.
Topic Titlebar: Located at the top of a Topic, this area collects metadata, which currently includes: topic title, timestamp of last activity, number of comments. Summary goes below the Topic Titlebar.
Summary: A Topic can be summarized (explain what is going on, or what are the main points of an ongoing discussion), or can have explanatory templates. Category links in here, will add the Topic to the category. Summary author is mentioned on the Summary bar.
Post: An atomic reply, comment, or object whose parent is a Topic.
Reply: A child Post of another Post.
Indentation: You create an indentation when you reply to an answer. That indentation is created to mark a digression from the main topic. The indentation is marked by a grey border and a padding on the left (on the right on right-to-left languages).
Structured Discussions-enabled: A wiki can specify which pages and namespaces should display a Structured Discussions board. For example, several projects' Talk pages, or all User_talk pages.
Subscription: Subscribing to a Structured Discussions Board is different from add the page to your watchlist: if you watch a Structured Discussions Board, you will receive notifications about the creation of each new topic on the page, no more. You have to add to your watchlist the Topics that further interest you to be notified of detailed answers. If you create a new topic, you will be auto-subscribed to it.
Moderation: A topic or a post can be "moderated" in 3 ways: Hide, Delete, and Suppress. Any user can hide a topic, sysops can delete, oversights can suppress.
Mark as resolved: A topic can be "marked as resolved": all answers to a particular topic are hidden, and a mark is added near of the title. You can expand the Topic by clicking on the Title or on the Summary.

Board

Each MediaWiki page object may have one (and only one) Board associated with it. A Board is a "bed" for subscribed Flow Topics.

Topics created on a Board are automatically subscribed to it, though a Board may be subscribed to additional Topics in the following ways:

A Topic is "moved" from one Board to another (either singularly or in bulk)
Two MediaWiki pages are merged, whereby their Boards are also merged

In the MVP, Board subscription should be limited to Topics that are created on that Board.

Board Header

Each Board shall have a (mostly) free-form "header" area available. This is will be a standard wikitext area that should be passed through Parsoid (and thus be VisualEditor compatible).

To avoid user confusion, this header section shall not accept wikitext "signature" codes nor shall it accept "colon indentation".

The header must be available for posting via the API (so that bots may update tags that exist for the Board).

Deleted Boards

If a Board's associated Page is deleted, the Board itself is deleted. [Note: See discussion at Thread:Talk:Flow Portal/Talk subpages.] Topics that the Board was subscribed to or owned are not deleted; however they may enter an "orphan" state (the Topic has no subscribers) whereby they are only discoverable through site search.

If the Page is recreated, the Board is also recreated, and all previous Topic subscriptions are to be restored.

Pagination Technology

Board Topics shall be collated into logical "pages" of 20 items (Topics) each. The first 20 Topics will be loaded immediately upon visitation to the Board.

For users with JavaScript, paging through the Board is done via an infinite scrolling technique. That is, the user simply continues to scroll through the Board. Additional pages are automatically loaded in the background (typically when the user scrolls to the 10th item in the stack).

For users without JavaScript, pagination controls will be provided at the top and bottom of the Topic stack. The pagination control system will behave thus:

Always show total number of pages and Topics
Always show links to jump to the first and last pages
Always show links to jump to the next and previous pages (if this value does not exist, the link still shows but is disabled)
Always show the current page
Always show links to the two most previous pages (if they exists in the stack)
Always show links to the two most next pages (if they exist in the stack)

Topics

A Topic is the largest atomic unit of a Flow Board. A Topic is a single discussion or extant workflow.

Topics are analogous to Talk Page "sections".

Topic Elements

For the MVP release, a Topic can consist of the following visible elements:

Title - the Topic title
Collapse Control - A control that allows the Topic to be visually opened and closed.
1. If the Topic has Posts within it that have not been read by the user, the control will have an additional visual element indicating such
Last Modified Timestamp - This timestamp will behave normally (see Timestamp Behavior)
Subscribe Control - analogous to a "watch" affordance. This allows the user to subscribe or unsubscribe from a topic. This functionality is not required for the MVP.
An Actions Menu - This is a menu affordance that will provide the user access to additional controls or activities related to the Topic (see Topic Functions)
One or more threaded Posts

Topic Functions

The following functions or views are available through the Topic's "actions" menu. Some functions require advanced user rights. Most actions invoke a modal dialog that asks for confirmation.

Mute Conversation

This function will disable Echo notifications for the user regarding this Topic. This function will open a modal dialog that prompts the user for confirmation before taking effect.

This function is not suggested for the MVP.

Close Topic

This function does not exist on Topics that are closed, hidden, deleted, or suppressed.

This function opens a modal dialog wherein the user is prompted for a summary for the Topic.

The dialog shall display the current title as well as a form that consists of a small text field, "Summary." A "Close Topic" button shall exist but shall be disabled until the value of the "Summary" field is not empty. A "cancel" affordance is also included.

The Topic summary must not be empty, nor may it fail additional constraints (such as AbuseFilter rules).

When saved, a line in the Topic's history will be created (User closed this topic with the summary of $SUMMARY). The Topic shall be marked closed and the Summary shall be displayed at the top of the Topic.

This will cause a bump in the Topic's last modified timestamp.

Re-Open Topic

This function only exists on topics that are closed. It does not appear on Topics that are hidden, deleted, or suppressed.

This function moves a Topic back from the "closed" state to the "open" state. Accessing it opens a modal dialog that asks for confirmation. When given, the Summary is removed from the Topic and the Topic will no longer be marked closed. A line in the Topic's history will be created (User re-opened the topic).

This will cause a bump in the Topic's last modified timestamp.

Delete Topic

This function does not exist on Topics that are deleted. It only appears for users with the "sysop" user right.

This function opens a modal dialog wherein the sysop is prompted for a reason for deleting the Topic.

The dialog shall display a form that consists of a small text field, "Reason." A "Delete Topic" button shall exist but shall be disabled until the value of the "Reason" field is not empty. A "cancel" affordance is also included.

The deletion reason must not be empty, nor may it fail additional constraints (such as AbuseFilter rules).

When saved, a line in the Topic's history will be created (User deleted this topic with a reason of $REASON). The Topic shall be marked deleted.

This will cause a bump in the Topic's last modified timestamp, though it will have no obvious effect.

Restore Topic

This function only exists on Topics that are deleted. It only appears for users with the "sysop" user right.

This function opens a modal dialog wherein the sysop is prompted for a reason for un-deleting the Topic.

The dialog shall display a form that consists of a small text field, "Reason." A "Restore Topic" button shall exist but shall be disabled until the value of the "Reason" field is not empty. A "cancel" affordance is also included.

The un-deletion reason must not be empty, nor may it fail additional constraints (such as AbuseFilter rules).

When saved, a line in the Topic's history will be created (User un-deleted this topic with a reason of $REASON). The Topic shall no longer be marked deleted.

This will cause a bump in the Topic's last modified timestamp.

Suppress Topic

This function does not exist on Topics that are suppressed. It only appears for users with the "suppression" user right.

TBD

Un-Suppress Topic

This function does not exist on Topics that are not suppressed. It only appears for users with the "suppression" user right.

TBD

View History

TBD

Edit Title

This function does not exist on Topics that are closed, hidden, deleted, or suppressed.

This function opens a modal dialog wherein the user is prompted for a new title for the Topic.

The dialog shall display the current title as well as a form that consists of one field, "New Title." A "Save Title" button shall exist but shall be disabled until the value of the "New Title" field is different from that of the current title and it is not empty. A "cancel" affordance is also included.

The Topic title must not be empty, nor may it fail additional constraints (such as AbuseFilter rules).

When saved, a line in the Topic's history will be created (User changed the title of this topic from $PREVIOUS_VALUE to $NEW_VALUE) and the Topic's title will be changed.

This will cause a bump in the Topic's last modified timestamp.

Permalink

Activating this function will open a modal dialog that will display several options for the user wherein they may obtain a permanent link to the Topic.

A full URL to the single Topic (good forever)
A full URL to the single Topic as it exists at that point in time
A local (wikitext) link to the single Topic (good forever)
A local (wikitext) link to the single Topic as it exists at that point in time

This isn't how it works in the alpha release, clicking the Permalink icon simply takes you to the URL of the topic or post. -- S Page (WMF) (talk) 01:29, 12 December 2013 (UTC)[reply]

Closed Topics

In the MVP, Topics may exist in one of two "workflow states": open or closed.

When the Topic's state is open, it may be modified and replied to normally.

When the Topic is closed, however, the following restrictions apply:

The title may not be edited
Posts may not be edited
The Topic does not accept new replies (no new Post creation)

Closed Topics must have a summary indicating why they have been closed. Closed Topics may be re-opened by anyone, at which time they may be interacted with normally.

Topic Order Stack

Topics are to be ordered within a Board chronologically by "last modified date", newest to oldest.

A Topic's last modified date will be updated when:

The Topic has been created
A new Post is added to the Topic
The Topic's title has been changed
The Topic changes workflow state (e.g., has been closed)
A Post within the Topic has been modified (edited, hidden, or deleted, but not suppressed)
The Topic has been merged with a different Topic
The Topic has been moved to a foreign Board

The following events do not modify the Topics last modified date:

Adding a new subscriber to the Topic
Splitting Posts from a Topic into a new Topic
Suppressing a Post (or Posts) within the Topic

Thread Depth Level

The maximum depth that Posts may be indented (thread depth level) is to be a configuration option with a default value of 5. This means that after 5 "levels" of indentation, Posts will cease to be visually indented further (retaining a visual level of 5).

Posts will continue to remember their "logical" depth level (stored in their "replied to" field). However, this will not be displayed or take effect unless those Posts are split from the Topic in question in such a manner where they would obtain a new depth level (that is lower than the threshold, 5).

Start New Discussion

All Boards will include an affordance for starting a new discussion (New Discussion Dialog). This shall be a form placed at the top of the Board (but below the Board Header). By default, the New Discussion Dialog will display minimally and will expand when interacted with.

The New Discussion Dialog will require two fields of data:

Topic Title - the Title for the new Topic
Topic Text - the text of the first Post within the Topic

The system will not allow the posting of a new Topic if either element is empty, contains errors, or otherwise fails (such as matching an AbuseFilter rule that would prevent posting).

If all criteria are met, a new Topic will be created on the Board and inserted in the logical location (likely at the very top of the Board's Topic stack, but it's possible that two people can modify Topics at the same time, pushing it down).

Reply to Discussion

(placeholder)

Collaborative Editing Section (Scratchpad)

(placeholder)

Timestamp Behavior

Unless otherwise noted, timestamps shall be displayed in relative time. That is, they will be displayed as "time ago," relative to the viewing user (e.g., "Last modified 4 hours ago"). Hovering over (or tapping on) the timestamp will display the timestamp in UTC format.