Flow/Functional Specifications/History

This document describes a set of functional requirements regarding the display of history pages in Topics and Posts for Flow.

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.

"Diffs" and Edit Summaries edit

In many cases, Flow does not have a concept of a "diff" nor does it have a need for edit summaries. When replying within a conversation, the action is typically atomic: a single reply is posted. Since Topics themselves are an accretion of content objects rather than continual modification of a singular text blob, there is no easy, compelling, or usable way to display specific changes in the conversation structure.

For certain, if a text item is modified, a diff view must be provided, but in the bulk of cases and log lines this will not be possible or even desired.

Further, in most cases, edit summaries are not required. The content of the Post is just that; the edit summary remains along the logical lines of "a reply was posted". Change summaries are requested (or required) for certain edits (say, when closing a Topic, or deleting one) but it may be desirable to automate this as much as possible.

From this it becomes obvious that history logs for Topics (and Boards) will be different than standard MediaWiki history pages.

The first difference is one of scope. In Flow, histories can be scoped scoped along object lines (though this is not how users think of them):

Board
Topic
Post
Summary
Scratchpad

Some elements (Post, Summary, Scratchpad, Board headers) are atomic (and will have object-level histories), while others are conglomerate and will have collected histories.

For example, when viewing the history of a Topic, the view will also include the history lines for all the Posts that are contained within the Topic. Likewise, viewing a Board's history will also show information about Topics (but not necessarily about Posts).

Open Questions edit

An area of concern is information density and pollution, especially at the "highest" or super-set level of history view. Does it make sense to include Post-level changes when viewing the history at the Board level? Would it be too much clutter, or would lack of detail prove to be limiting and make the view useless?

Of further interest is the idea that a Board has relatively few actions that are "historical" to it. Topics are not really organic parts of a Board (that is, a Board is not comprised of Topics in the same way a Topic is comprised of Posts). Rather, Boards are more akin to containers of pointers to Topics.

Historic Events edit

A line in the history log shall be created when the following events happen. Suppression activities may change the visibility of a log line.

Board Level edit

The Board header is created
The Board header is modified
The Board header is deleted
An edit to the Board header is suppressed
A new Topic is created
A Topic is attached to the Board
A Topic is split (similar to created but logged as a different action)
Multiple Topics are merged
A Topic is hidden
A Topic is restored (unhide)
A Topic is deleted
A Topic is undeleted
A Topic is suppressed
A Topic is unsuppressed

Topic Level edit

The Topic is created
The Topic title is modified
The Topic is moved (between Boards)
The Topic is attached to a foreign Board
The Topic is closed
The Topic is re-opened
The Topic is hidden
The Topic is restored (unhide)
The Topic is deleted
The Topic is undeleted
The Topic is suppressed
The Topic is unsuppressed
The Topic is Summarized
The Topic Summary is modified

Post Level edit

The Post is created
The Post is edited
The Post is hidden
The Post is restored (unhide)
The Post is deleted
The Post is undeleted
The Post is suppressed
The Post is unsuppressed
The Post is moved to a new Topic (split or merged)

Scratchpad Level edit

A Scratchpad is created
The Scratchpad is edited
The Scratchpad is hidden
The Scratchpad is restored (unhide)
The Scratchpad is deleted
The Scratchpad is undeleted
The Scratchpad is suppressed
The Scratchpad is unsuppressed

Summary Level edit

A Summary is created (separately from Topic closure)
The Summary is edited
The Summary is hidden
The Summary is restored (unhide)
The Summary is deleted
The Summary is undeleted
The Summary is suppressed
The Summary is unsuppressed

User Experience edit

A mockup showing the history of a Board
A mockup showing the history of a Topic
A mockup showing three states of a modified Post

General Thoughts edit

History pages for Flow should not be displayed as simply (and ugly) as normal Mediawiki history lines. They should be broken up with smaller headers for each month. They should be in tables, with hard column edges and row stripes.

Datestamps should be in full format (not time relative). This is a different viewing mode than the conversation mode.

As in Flow posts, usernames should link to user page and expand on mouseover to show "(Talk | contribs)" Username/signature display should be in a UX element spec

Board History edit

Board histories will track only "Board level" events. Topic level events will not appear here, though links to the Topic history screens will exist.

Within the table, clicking on the Topic title (or the "view" link) will bring the user to the "Single Topic" view of the Topic. Clicking on the "History" link will zoom the user to the Topic history view.

Clicking on a datestamp should bring the user to the Board view as it existed at that time. This may not be performant, however (lots of extra calls).

In cases where a diff view is available, a link is provided to it. This will go to a standard Mediawiki diff page.

Note that many standard control options found on history pages are missing. This is either because they do not make sense in the context of the structured data format or because there are in-situ controls (e.g., restoring hidden posts). We do not want people mucking with content without actually seeing the content they are mucking with.

Affordance Issue edit

Typically, histories for pages are accessed via a "History" tab. However, Flow Boards are technically "Special" pages (which do not have histories). Most Flow Boards will be accessed through "talk" namespaces (which do have "History" tabs.) Whether or not there should be a "History" tab becomes a question.

For consistency's sake, it is the current recommendation to have a History tab on the Board, which then leads to the Board history. This may create user confusion, however - especially if experienced editors go to it assuming that they can find Topic-level histories.

Note that better options are being explored.

Topic History edit

Topic histories will typically open in modal dialogs, though they are in effect "pages".

Clicking on the "comment" link will bring the user to the Single Topic view of the page, scrolled to that specific Post. The Post will be highlighted. Clicking on any datestamp will bring the user to a permanent link for the Topic at that point in time.

Post History edit

Post histories shall behave in most regards like standard MediaWiki history pages. When accessed from the Flow interface, they will appear in modal dialogs. It is worth noting that the only way to access only a Post's history from the interface is if it has been edited. The only other way to access Post changes is through the Topic history.

In Situ Post Modification Notice edit

If a Post has been modified, a notice shall appear in the Post indicating that the Post has been modified, by whom, and when. This notice will contain an affordance that will show the user the diff between the two revisions (a normal MediaWiki diff) in a modal dialog as well as a link to the User page of the User who made the edit.

If multiple people have made edits to the Post, only the most recent editor will be named but the count of editors will be displayed ("Modified 25 minutes ago by Username and 2 others").

Design edit

Design talkpage history
Design topic history
Size specs