Workflow: Philosophy & Guidance

Workflow: Philosophy and Guidance

Workflow for the MMI site was designed around the concepts we think are needed for the site, and the capabilities Drupal enables. This document describes the user scenarios/requirements for the workflow of MMI documents, and is not essential for guests or new users of the site.

The workflow is the way documents are managed as they are created, reviewed, and published. The workflow engine uses the user role (which describes what a site user can do), the existing content state (where the document is in the workflow/publication process), and workflow rules (descriptions of who can make which changes to the content state) to determine the acceptable changes in the content state.

An overarching goal for the workflow is to make it as simple as possible while meeting the needs of the site. The workflow must support a typical editorial process of review and rewrite, often multiple times, before content is published. The terminology in the workflow should be self-explanatory. For additional information, see "Adding / Editing Content Form - The Detailed Explanation."

Content on the MMI site is displayed at 3 levels of visibility:

  • visible only to the author
  • visible to other registered users
  • visible to everyone

Basic (Stable) Content States

The fundamental content states are private, which is not visible to anyone except the owner, and public, which is visible to everyone. Only reviewers can put content into the public state. Only authenticated authors can put content into the private state (create content that is not visible to others).

When documents are in private or public states they are not awaiting further action, thus these content states are considered stable. (Although we hope the author of a private document will someday make it available so everyone can benefit, and public documents certainly can change over time.)

We use the private content state to indicate that material is not ready for review. All contributions of anonymous users are immediately made accessible for review.

Reviewing Cycle Content States

When a document is in a review cycle, its status is either reviewable (awaiting review) or pending (awaiting revisions). These categories do not fully describe the state of the document, because the state must also indicate visibility. As we discussed in the requirements, there are 3 levels of visibility: private, members-only, and public. By combining the visibility levels with the review cycle status, we come up with the 6 content states in the Reviewing Content States Table below.

 

Review Status

Visibility

Reviewable

Active

Private
anon-created
anonymous only
private
members only
Members-Only member-draft-reviewable member-draft
Public public-reviewable public

Reviewing Content States Table

As you might expect, only reviewers can say that a reviewable document needs more changes before it can be published, so any transition in review status from reviewable to pending must be performed by a reviewer. Similarly, the author must decide when enough changes have been made that the document should be submitted for another review, so review status changes from pending to reviewable are driven by the author.

We will review a few common document workflows shortly, but first we want to highlight a few special cases. There are two particularly interesting content states, Private-Reviewable and Public-Reviewable. When anonymous users create content, we want the content to be reviewed immediately, without anyone else on the site seeing it. The Private-Reviewable state allows for this. If a reviewer thinks changes are needed for this content, a member must be assigned as the owner. The assigned owner will make the necessary changes, and after doing so, make the content Member Draft-Reviewable.

On the other hand, there is this converse scenario. We usually want site content to be reviewed before it is published. However, it is often the case that content is unlikely to be controversial, and is important or timely enough that it should not be held up for review. (For example, event announcements are usually in this category.) Thus, certain members on the MMI team are deemed 'trusted', and can create content that is immediately visible, even though it has not been reviewed. By creating the Public-Reviewable state, the content is flagged as awaiting review, but in the meantime, can be seen by any visitor to the site.

Workflow Scenarios

Typical Content Creation

When a member creates a new document, he or she may work on it for a while without having it reviewed. Thus we set the default document state to Private.

When the document is ready for others to see, the member sets its state to Member Draft-Reviewable. At this point, other logged-in members can see the document as well. This is an advantage of membership, and is an appropriate level of visibility for such a document.

A reviewer in that area is delegated the responsibility to review such documents, and will receive a notification that the document is available for review. If the reviewer considers the document not ready for publication, he or she describes the document's issues, and sets its state to Member Draft-Pending. This generates a notification back to the member with the issues attached or referenced, and now the member must make the appropriate changes before resubmitting the document as Member Draft-Reviewable.

If the reviewer considers the document ready for publication—possibly requiring only minor modifications, which the Reviewer can perform—then he or she makes any minor modifications deemed necessary, and sets the document to Public.