Flow/Functional Specifications/History

From MediaWiki.org
Jump to navigation Jump to search

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".

A board is a group of subjects. A talk page converted to Structured Discussions is a board. There is only one board per page.
Content on the right column of a Board (introductory text, templates, and similar). Category links in here, will add the Board to the category.
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.
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.
An atomic reply, comment, or object whose parent is a Topic.
A child Post of another Post.
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.
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.
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]

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").