MindTouch Moderator and Collaborative Publishing

Goals

1. Allow users to contribute content in a safe environment where it can be reviewed by moderators before it is published back.
2. Allow moderators to discover and manage user contributions by providing tools to review them, accept or reject individual contributions, and publish the final result.
3. Enable moderators to change published content directly without having to create or edit a draft. 
4. Edits to a page are reflected immediately as before while edits to a draft are not visible until it's published.

Non-Goals

These are the use cases we will purposely not be solving in this iteration of draft pages.

1. This feature will not be utilized as an autosave feature
2. This feature will not benefit individuals who want to create their own drafts of a page
3. This feature will not benefit "preview" scenarios when trying to write complex DekiScript applications that rely on state of the current page

How it works

The drafts module will be built atop the MindTouch platform, utilizing two new API features (import/export, "delete" a page/file revision). The module will be sold as a part of the MindTouch Enterprise package. After the drafts module is installed in MindTouch, part of the set-up will entail setting up the /drafts/ root-level hierarchy, which may be permissioned without BROWSE, so it does not show up search results or nav pane - essentially the page exist, but using permissions it can be made non-discoverable.

The UI module will piggyback off of PHP hooks to inject custom views: view draft, edit draft, confirm publish, and find drafts. Custom work will be required to implement drafts into skinning, without making changes to the skinning engine.

From a end-user standpoint, the UI should give the impression that much like talk: pages, drafts exist as a 1:1 relationship to a page. The UI should mentally link these concepts visually in the skin (Figure 1). Each draft page has both a view & edit state - when in view state, the skin should maintain a visual cue of its different state. (Figure 2)

Figure 1: Default toolbar view of MindTouch with drafts enabled - "Draft page" appears

Figure 2: Default when you click "Draft page" - it is the view mode of drafts.
Visual indicators indicate an informational message as well as a title icon.

On systems which have installed drafts, users will be able to view the draft always by hitting a 'draft' link. For non-moderators, "edit page" will automatically load the draft for editing (as opposed to simply being disabled) - upon saving, the page will redirect to the draft view mode (with an explicit notice of it being appended to a queue of changes awaiting moderation) - see figure 3. For moderators, 'edit page' will maintain its original behavior - to edit a draft, moderators will have to explicitly go to the draft page and edit this page.

Figure 3: Edit mode of a system with drafts, for non-moderators

Figure 4: Upon successful save of a draft - redirects back to live version with a message

When a draft is edited, users will have an option of sending a notification to the moderator that this copy is ready for review and publishing - this notification does not lock the page - it simply is an email notification. Moderators will be able to also discover drafts through a specialized "Recent Drafts" view, which will show all drafts updated in reverse chronological order. 

On the view draft page, a "publish" link will appear in the toolbar for moderators - see figure 5. This will take the moderator to a confirmation view, which they will review the final view of the page, with a list of attributions or revisions (which one is utilized will be determined by the underlying spec) which the moderator will check or uncheck before sending the draft to the live copy.

Figure 5: Moderator's publish button in view mode of draft

Upon publish, the files, tags, properties, will all be written back to the live copy. Attribution will be granted to the users who contributed to the draft and will appear in recent changes/revision history of the original page.

Use Cases 

The following use cases describe how users and moderators create, edit, groom, and publish drafts

Use Case 1: User wants to edit a page for which there is no draft

1. user clicks on "edit draft" button on the page
2. the app creates the draft by copying the head revision of the current page, attachments, and properties to a draft page which goes in the configured location (such as drafts/{id}) where {id} is the id of the original page
3. the app then checks if the current page has subscribers, if so it subscribes them to the newly created draft
4. the app then opens the draft in edit mode
5. when the user saves the draft, it notifies the subscribers about the change

Use Case 2: User wants to edit a page for which there is already a draft

1. user clicks on "edit draft" button on the page
2. the app then open the draft page in edit mode
3. when the user saves the draft, it notifies the subscribers about the change

Use Case 3: Moderator needs to change a page regardless if it has a draft or not

1. moderator clicks on "edit page"
2. the app then open the current page in edit mode
3. when the moderator clicks save, the changes are immediately applied to the page

Use Case 4: Moderator wants to publish a draft of a page that has not been modified since the draft was created

1. moderator goes to the draft
2. moderator views history of the draft
3. moderator removes any unwanted revisions from the draft (see page revision deletion below)
4. when the moderator clicks "publish", contributions made to the draft are applied to the original page
5. the app then deletes the draft page and redirects the moderator to the page

Use Case 5: Moderator wants to publish a draft of a page that has been modified since the draft was created

1. moderator goes to the draft
2. moderator views history of the draft
3. moderator removes any unwanted revisions from the draft (see page revision deletion below)
4. when the moderator clicks "publish", the app shows a warning message that the page has been modified since the draft was created with a link to view changes to the page since the draft was created. the app uses the page revision to determine if the draft is older
5. when the moderator clicks "accept", contributions made to the draft are applied to the original page
6. the app then deletes the draft page and redirects the moderator to the page

Use Case 6: Moderator wants to publish a draft of a page that has been deleted

1. moderator goes to the draft
2. moderator views history of the draft
3. moderator removes any unwanted revisions from the draft (see page revision deletion below)
4. when the moderator clicks "publish", the app shows a warning message that the page has been deleted since the draft was created
5. when the moderator clicks "confirm", contributions made to the draft are applied to the original page using the page path
6. the app then deletes the draft page and redirects the moderator to the page

Use Case 7: A user is finished with the draft and wants to let a moderator know that it is ready for review

1. user clicks the "ready for review" button on the draft
2. the app add the "ready" tag to the draft, which then shows the draft on the moderator dashboard

Use Case 8: Moderator deletes the draft page

1. moderator goes to the draft
2. moderator is able to delete the page
3. the draft can be recreated by a user with access and the previously deleted draft is not visible

Draft creation and storage

The preset location /drafts/{pageid} where {pageid} is the id of the original page is used for storage of draft pages.

Permissions

Approach 1

• A 'draft editors' group is created and contains all users that are allowed to view and make draft changes. The role of this group does not include CHANGEPERMISSION.
• The /drafts page is set to private with a grant given to 'draft editors' allowing anyone in the group to view, create, and edit drafts.
• Guest users will not have access to /drafts because the Anonymous user is not a member of 'draft editors' and thus they will not be able to see or edit them

Approach 2

• The default contributor role given to all users does not include CHANGEPERMISSION.
• The homepage and other pages are restricted as Semi-Public with a contributor grant given to the 'Moderator' group.
• The /drafts page has no restriction and no grants set.
• The Anonymous user has a Viewer role and will be able to see but not edit drafts

Draft publishing

• Content is copied back to the original page including page text, page properties, tags, page title, and attachments. Refer to sections below for more details of the publish behavior with respect to these content elements.
• If the original page has been modified since the creation of the draft, a warning will be displayed with a link to all revisions of the original that may not be reflected in the draft.
• Draft pages are deleted upon publish. This allows drafts that are recreated from an original page to start off without having already published revisions making draft changes difficult to interpret.

Attribution

Publish head revision for each attributed user

• Moderator looks at the history of the draft and hides any revisions that have inappropriate or unwanted content
• The users from all non-hidden page revisions are collected and the head revision of the draft is copied on top of the original page for each attributed user.
• The head revision of the draft is copied on top of this with the attribution going to the moderator. Note that the moderator will not be attributed twice if he or she made any page edits to the draft.

Publish head revision only (This approach is not implemented)

• Head revision of draft is copied to the original page. Only the publisher gets the attribution on the new revision of the original page. Moderator can optionally hand write a comment attributing the authors of the draft.
• Keeps the history of the original page clean and brief but no attribution is given to draft editors other than the optional edit summaries.

Publish all non-hidden revisions (This approach is not implemented)

• Moderator looks at the history of the draft and hides any revisions that have inappropriate or unwanted content
• All remaining visible revisions are copied to the original page with the original authors preserved
• Preserves the edits done by the moderator selected revisions and encourages users to clean up the draft before making edits if they don't want to risk their revision getting hidden. Encourages everyone to take part in moderation before making changes on top of inappropriate edits.

Attachments and Images

The draft page should look and feel as much as the original. A step of the draft creation process is to copy the head revision of all attached files from the original page to the new draft page. Any file links to the attachments on the original page will be changed to links of the corresponding images on the draft page. Copying these attachments has the following benefits:

• New uploads of referenced images located on the page will be reflected visually immediately.
• Dekiscript embedded within the page that relies on the current pages attachments will continue to function

The downside of this is that creating a draft in some cases may become a much more time consuming and intensive operation when many or large attachments exist.

Only head revision of new or updated attachments on the draft are moved back to the original page upon publish.

Attachments on a draft that were copied from the original page are only moved back if they have more than one revision to not copy over attachments that were not modified.

Attachments created on a draft are copied over to the original page upon publish.

Attachments that were copied to the draft during creation and then subsequently deleted will be deleted from the original page upon draft publish.

Search

Drafts are indexed like any other page but may be hidden from search results throught the use of permissions. Users that do not have BROWSE access to the drafts will not see them appear in search results.

Recent changes and feeds

Changes to the drafts such as page edits, file attachments, comment postings, etc will show up in recent changes and feeds as they would for any other page.

Tags

Tags from the original page are copied to the draft when the draft is created. Upon publish, any new tags on the draft are copied to the original and any tags deleted on the draft that originated from the original page are removed from the original as well.

Page and File Properties

Page and file properties are copied from the original page to the draft when the draft is created. Upon publish, any new page and file properties on the draft are copied to the original and any properties deleted on the draft that originated from the original page are removed from the original as well.

Page Comments

Comments in the original page will not be included in created drafts.

Comments saved to a draft page will not be copied to the original page as part of a publish.

Notifications

Users may subscribe to changes of a draft page but no subscriptions are given automatically. The notification list of the original page is not copied to a draft. If a user subscribes to a draft that gets published and then recreated, since it's a new page the user will not be subscribed to the new draft.

Subpages

Creating a draft of an original page containing subpages will only make a draft of the original page itself and not its subpages.

Users may be allowed to make subpages under the draft page. These pages will not be included in the publish and will be deleted along with the draft after publish.

Page Display Title

The draft's display title is copied from the original page upon draft creation if the title has been set. Likewise, upon publish the latest display title of the draft is copied to the original page.

Page Language

If a language is set or changed on the draft, it will be set accordingly on the original page upon publish.

Draft Page Locking

A moderator has the ability to lock a page from being edited using the permission system or to only allow it to be edited by specific users. This may become useful for controversial content that is experiencing a lot of malicious edits.

Technical Requirements

Feature 1: Hide Page/File Revision

An administrator must be able to hide a page/file revision from the page/file history. A hidden page/file revision creates a gap in the page/file history and may not be retrieved via the API without admin access.  In other words, the content is gone for all practical purposes but the metadata for it is still available (original editor, timestamp).

Additional motivation: the ability to hide a page/file revision has come up to remove spam content from the site and has broader applicability.

Spec for page and file revision hiding

Feature 2: Page Revision Copy

The API must provide a feature to copy a given page revision to another location.  The page copy includes the page content, files, and properties as of that revision.  If the copied revision is the head revision, it will also copy the current tags of the page and title (since tags and title don't have revisions).  A page copy operation is essentially an export/import operation but optimized to operate within the same site.

Additional motivation: the ability to copy a page (usually head) to another location has broader applicability; it may also be used to create a better page revert since it would also revert content, properties, and files.

Feature 3 (optional): Page Feeds based on Search Queries

All a user to subscribe to a set of pages based on a search query.  The resulting feed is similar to the existing site feed or sub-tree feed, but only includes pages returned by the search queries.