[wp-meta] [Making WordPress.org] #786: Editorial flow for Explanations

[Making WordPress.org]

#786: Editorial flow for Explanations
-------------------------+-------------------------------------
Reporter:  DrewAPicture  |      Owner:
    Type:  task          |     Status:  new
Priority:  normal        |  Component:  developer.wordpress.org
Keywords:  has-patch     |
-------------------------+-------------------------------------
 In devising a plan for migration of information from function, hook, and
 class reference pages from the Codex, it became immediately apparently
 that we would need some mechanism to handle the content that will make up
 the "Explanation" section of any given reference article.

 Several weeks ago, @coffee2code and I devised an editorial workflow that
 hoped to accomplish several goals. Those are realized in the attached
 patch and described below:

 * '''Store Explanations as a separate post type'''

 After going back and forth quite a bit about what we'd like to be able to
 do with Explanations, we decided that storing them in a separate post type
 was the way to go. With that, we get:

 * Revisions independent of the reference post
 * Publishing status independent of the reference post
 * More fine-grained control over permissions.

 * '''Create an interface within the reference post type editing screen'''

 In light of making the editorial flow for Explanations separate, the goal
 of the UI in the reference post editing screen was to make a quickly-
 grokked interface that would include:

 * The post status of the explanation
 * Last Modified information (if published)
 * Links for creating (AJAX), editing, and/or un-publishing (AJAX)
 depending on the current post status. We chose to omit the ability to
 blindly publish a drafted explanation.

 '''No explanation exists''':

 Nonexistent explanations have a status of 'None', and a 'Create
 Explanation' link is shown. Clicking the link, a draft explanation is
 created via AJAX with the post_parent set for reference post. The status
 label updates to 'Drafted', the create link disappears and is replaced
 with an 'Edit Content' link pointing to the editing screen for the new
 explanation.

 [[Image(http://f.cl.ly/items/3K431a1W3o061k0r2l33/Screen%20Shot%202014-12-16%20at%206.10.49%20PM.png)]]

 '''A drafted explanation exists''':

 Drafted explanations have a status of 'Drafted' (draft) and an 'Edit
 Content' link is shown. Clicking the link takes you to the editing screen
 for the explanation. At the top of this screen is information about what
 reference post the explanation is associated with including a link back to
 the reference post-editing screen.

 [[Image(http://f.cl.ly/items/0Q09120q3y0g39430V3G/Screen%20Shot%202014-12-16%20at%206.08.23%20PM.png)]]

 '''An explanation exists and is 'pending review'''':

 Explanations pending review have a status of 'Pending Review', and the
 workflow is basically the same as with 'Drafted' explanations. The main
 difference is that this status could be used in concert with a future
 front-end submission form for reference posts lacking an explanation
 section. That's Phase II.

 '''A published explanation exists''':

 Published explanations have a status of 'Published', and 'Edit Content'
 and 'Un-publish' links are shown. Clicking 'Un-publish' sets the
 explanation post status to draft via AJAX. The status label updates to
 'Draft' and the 'Un-publish' link disappears. Clicking the 'Edit Content'
 link takes you to the editing screen for that explanation.

 [[Image(http://f.cl.ly/items/3u052n2P3M422H0N3X1X/Screen%20Shot%202014-12-16%20at%206.08.44%20PM.png)]]

 [[Image(http://f.cl.ly/items/1m470w360u0c3T260K27/Screen%20Shot%202014-12-16%20at%206.13.57%20PM.png)]]

 '''Other stuff:'''

 * An explanation must be published to show up on the front-end. Two
 template tags were introduced in the patch `get_explanation()` and
 `get_explanation_field()`.
 * The Parsed Content meta box was changed back to using the post content
 for the description
 * parsed-content.js was renamed to admin.js and re-purposed

 '''What's left:'''

 It works, but:

 * The AJAX interactions could probably be improved, possibly slowed down
 with some kind of spinner or visual feedback.
 * Though errors are properly sent via the AJAX handlers, there isn't yet
 any kind of visual feedback for that.

--
Ticket URL: <https://meta.trac.wordpress.org/ticket/786>
Making WordPress.org <https://meta.trac.wordpress.org/>
Making WordPress.org