Change is good, but show your work: Here’s a WordPress revisions plugin

You are viewing an old revision of this post, from 3 August, 2010 @ 6:23. See below for differences between this version and the current revision.

A couple of weeks ago I posted a manifesto. I said Web publishers should let themselves change published articles and posts whenever they need to — and make each superseded version accessible to readers, the way Wikipedians and software developers do.

This one simple addition to the content-management arsenal, known as versioning, would allow us to use the Web as the flexible medium it ought to be, without worrying about confusing or deceiving readers.

Why not adopt [versioning] for every story we publish? Let readers see the older versions of stories. Let them see the diffs. Toss no text down the memory hole, and trigger no Orwell alarms.

Then I asked for help creating a WordPress plugin so I could show people what I was talking about. Now, thanks to some great work by Scott Carpenter, we have it. It’s working on this blog. (You can get it here.) Just go to the single-page form of any post here (the one that’s at its permalink URL, where you can see the comments), and if the post has been revised in any way since I published it, you can click back and see the earlier versions. You can also see the differences — diffs — highlighted, so you don’t have to hunt for them.

The less than two weeks since my post have given us several examples of problems that this “show your work” approach would solve. One of them can be found in the story of this New York Times error report over at MediaBugs.

An anonymous bug filer noticed that the Times seemed to have changed a statistic in the online version of a front-page story about where California’s African Americans stood on pot legalization. As first published, the story said blacks made up “only” or “about 6 percent” of the state population; soon after it was posted, the number changed to “less than 10 percent.” There’s “>a full explanation of what happened over at MediaBugs; apparently, the reporter got additional information after the story went live, and it was conflicting information, so reporter and editor together decided to alter the story to reflect the new information.

There is nothing wrong with this. In fact, it’s good — the story isn’t etched in stone, and if it can be improved, hooray. The only problem is the poor reader, who was reading a story that said one thing at one time, and something different when he returned. The problem isn’t the change; it’s the failure to note it. Showing versions would solve that.

Another Times issue arose yesterday when the paper changed a headline on a published story. The original version of a piece about Tumblr, the blogging service, was headlined “Facebook and Twitter’s new rival.” Some observers felt this headline was hype. (Tumblr is successful but in a very different league from the vastness of Facebook and Twitter.) At some point the headline was rewritten to read “Media Companies Try Getting Social With Tumblr.” Though the article does sport a correction now fixing some other errors, it makes no note of the headline change.

I don’t know what official Times policy is on headline substitution. Certainly, Web publications often modify headlines, and online headlines often differ from print headlines. Still, any time there’s an issue about the substance of a headline, and the headline is changed, a responsible news organization should be forthright about noting the change. Versioning would let editors tinker with headlines all they want.

I do not mean to single out the Times, which is one of the most scrupulous newsrooms around when it comes to corrections. Practices are in a state of flux today. News organizations don’t want to append elaborate correction notices each time they make a small adjustment to a story. And if we expect them to, we rob ourselves of the chance to have them continuously improve their stories.

[I'm adding some text right here that I'm going to delete in a minute, just to provide an illustration of some versioning in action on this post...]

The versioning solution takes care of all of this. It frees writers and editors to keep making their work better, without seeming to be pulling a fast one on their readers. It’s a simple, concrete way to get beyond the old print-borne notion of news stories as immutable text. It moves us one decent-sized step toward the possibilities the Web opens up for “continuing stories,” iterative news, and open-ended journalism.

How the plugin happened: I got some initial help from Stephen Paul Weber, who responded to my initial request to modify the existing “post revision display” plugin so as to only list revisions made since publication. Weber modified the plugin for me soon thereafter (thank you!). Unfortunately, I failed to realize that that plugin, created by D’Arcy Norman, only provided access to version texts to site administrators, not regular site visitors.

Scott Carpenter, the developer who’d originally pointed out the existing plugin to me, stepped up to the plate, helped me work up a short set of requirements for the plugin I wanted, and set to work to create it. Here’s his full post on the subject, along with the download link for the plugin. We went back and forth a few times. He thought of some issues I hadn’t — and took care of them. I kept adding new little requirements and he knocked them off one by one. I think we both view the end-product as still “experimentally usable” rather than a polished product, but it’s working pretty well for me here.

As the author of a whole book on why making software is hard, I’m always stunned when things go really fast and well, as they did here. Thanks for making this real, Scott!

If you run WordPress and like the idea of showing your work, let us know how it goes.

Report an errorClose

Post Revisions:

Changes:

3 August, 2010 @ 6:23Current Revision
Title
Change is good. But show your work!  Change is good, but show your work: Here's a WordPress revisions plugin
Content
A couple of weeks ago <a href="http:// www.wordyard.com/2010/07/ 21/politico-slate-and-story- versioning/">I posted a manifesto.</a> I said Web publishers should let themselves change published articles and posts whenever they need to -- and make each superseded version accessible to readers, the way Wikipedians and software developers do.  A couple of weeks ago <a href="http:// www.wordyard.com/2010/07/ 21/politico-slate-and-story- versioning/">I posted a manifesto.</a> I said Web publishers should let themselves change published articles and posts whenever they need to -- and make each superseded version accessible to readers, the way Wikipedians and software developers do.
This one simple addition to the content-management arsenal, known as versioning, would allow us to use the Web as the flexible medium it ought to be, without worrying about confusing or deceiving readers.  This one simple addition to the content-management arsenal, known as versioning, would allow us to use the Web as the flexible medium it ought to be, without worrying about confusing or deceiving readers.
<blockquote> <blockquote>
Why not adopt [versioning] for every story we publish? Let readers see the older versions of stories. Let them see the diffs. Toss no text down the memory hole, and trigger no Orwell alarms. Why not adopt [versioning] for every story we publish? Let readers see the older versions of stories. Let them see the diffs. Toss no text down the memory hole, and trigger no Orwell alarms.
</blockquote> </blockquote>
Then I <a href="http:// www.wordyard.com/2010/07/ 23/help-with- a-wordpress- plugin-for-published- versions/">asked for help creating a WordPress plugin</a> so I could show people what I was talking about. Now, thanks to some great work by Scott Carpenter, we have it. It's working on this blog. (You can get it <a href="http:// www.movingtofreedom.org/2010/ 07/30/wordpress- plugin-post- revision-and- diff-viewer/ ">here</a>.) Just go to the single-page form of any post here (the one that's at its permalink URL, where you can see the comments), and if the post has been revised in any way since I published it, you can click back and see the earlier versions. You can also see the differences -- diffs -- highlighted, so you don't have to hunt for them. Then I <a href="http:// www.wordyard.com/2010/07/ 23/help-with- a-wordpress- plugin-for-published- versions/">asked for help creating a WordPress plugin</a> so I could show people what I was talking about. Now, thanks to some great work by Scott Carpenter, we have it. It's working on this blog. (You can get it <a href="http:// www.movingtofreedom.org/2010/ 07/30/wordpress- plugin-post- revision-and- diff-viewer/ ">here</a>.) Just go to the single-page form of any post here (the one that's at its permalink URL, where you can see the comments), and if the post has been revised in any way since I published it, you can click back and see the earlier versions. You can also see the differences -- diffs -- highlighted, so you don't have to hunt for them.
The less than two weeks since my post have given us several examples of problems that this "show your work" approach would solve. One of them can be found in the story of <a href="http:// mediabugs.org/ bugs/marijuana- story-changed- black-population- figure-without- notice">this New York Times error report over at MediaBugs</a>.  The less than two weeks since my post have given us several examples of problems that this "show your work" approach would solve. One of them can be found in the story of <a href="http:// mediabugs.org/ bugs/marijuana- story-changed- black-population- figure-without- notice">this New York Times error report over at MediaBugs</a>.
An anonymous bug filer noticed that the Times seemed to have changed a statistic in the online version of a front-page story about where California's African Americans stood on pot legalization. As first published, the story said blacks made up "only" or "about 6 percent" of the state population; soon after it was posted, the number changed to "less than 10 percent." There's <a href="<a href="http:// mediabugs.org/ bugs/marijuana- story-changed- black-population- figure-without-notice">">a full explanation of what happened</a> over at MediaBugs; apparently, the reporter got additional information after the story went live, and it was conflicting information, so reporter and editor together decided to alter the story to reflect the new information.  An anonymous bug filer noticed that the Times seemed to have changed a statistic in the online version of a front-page story about where California's African Americans stood on pot legalization. As first published, the story said blacks made up "only" or "about 6 percent" of the state population; soon after it was posted, the number changed to "less than 10 percent." There's <a href="http:// mediabugs.org/ bugs/marijuana- story-changed- black-population- figure-without-notice">a full explanation of what happened</a> over at MediaBugs; apparently, the reporter got additional information after the story went live, and it was conflicting information, so reporter and editor together decided to alter the story to reflect the new information.
<i>There is nothing wrong with this.</i> In fact, it's good -- the story isn't etched in stone, and if it can be improved, hooray. The only problem is the poor reader, who was reading a story that said one thing at one time, and something different when he returned. The problem isn't the change; it's the failure to note it. Showing versions would solve that.  <i>There is nothing wrong with this.</i> In fact, it's good -- the story isn't etched in stone, and if it can be improved, hooray. The only problem is the poor confused reader, who saw a story that read one way before and now reads another way. The problem isn't the change; it's the failure to note it. Showing versions would solve that.
<a href="http:// www.wordyard.com/wp-content/ uploads/2010/ 08/tumblr-story- hed2.png"><img src="http://www.wordyard.com/ wp-content/uploads/2010/08/ tumblr-story-hed2.png" alt="" title="tumblr story hed2" width="240" height="260" class="alignright size-full wp-image-2606" /></a>Another Times issue arose yesterday when the paper changed a headline on a published story. The original version of <a href="http:// www.nytimes.com/2010/08/02/ technology/02tumblr.html">a piece about Tumblr,</a> the blogging service, was headlined "Facebook and Twitter's new rival." Some observers felt this headline was hype. (Tumblr is successful but in a very different league from the vastness of Facebook and Twitter.) At some point the headline was rewritten to read "Media Companies Try Getting Social With Tumblr." Though the article does sport a correction now fixing some other errors, it makes no note of the headline change. <a href="http:// www.wordyard.com/wp-content/ uploads/2010/ 08/tumblr-story- hed2.png"><img src="http://www.wordyard.com/ wp-content/uploads/2010/08/ tumblr-story-hed2.png" alt="" title="tumblr story hed2" width="240" height="260" class="alignright size-full wp-image-2606" /></a>Another Times issue arose yesterday when the paper changed a headline on a published story. The original version of <a href="http:// www.nytimes.com/2010/08/02/ technology/02tumblr.html">a piece about Tumblr,</a> the blogging service, was headlined "Facebook and Twitter's new rival." Some observers felt this headline was hype. (Tumblr is successful but in a very different league from the vastness of Facebook and Twitter.) At some point the headline was rewritten to read "Media Companies Try Getting Social With Tumblr." Though the article does sport a correction now fixing some other errors, it makes no note of the headline change.
<a href="http:// www.wordyard.com/wp-content/ uploads/2010/ 08/tumbrhedchanged2.png"><img src="http://www.wordyard.com/ wp-content/uploads/2010/08/ tumbrhedchanged2.png" alt="" title="tumbrhedchanged2" width="350" height="143" class="alignleft size-full wp-image-2607" /></a>I don't know what official Times policy is on headline substitution. Certainly, Web publications often modify headlines, and online headlines often differ from print headlines. Still, any time there's an issue about the substance of a headline, and the headline is changed, a responsible news organization should be forthright about noting the change. Versioning would let editors tinker with headlines all they want. <a href="http:// www.wordyard.com/wp-content/ uploads/2010/ 08/tumbrhedchanged2.png"><img src="http://www.wordyard.com/ wp-content/uploads/2010/08/ tumbrhedchanged2.png" alt="" title="tumbrhedchanged2" width="350" height="143" class="alignleft size-full wp-image-2607" /></a>I don't know what official Times policy is on headline substitution. Certainly, Web publications often modify headlines, and online headlines often differ from print headlines. Still, any time there's an issue about the substance of a headline, and the headline is changed, a responsible news organization should be forthright about noting the change. Versioning would let editors tinker with headlines all they want.
I do not mean to single out the Times, which is one of the most scrupulous newsrooms around when it comes to corrections. Practices are in a state of flux today. News organizations don't want to append elaborate correction notices each time they make a small adjustment to a story. And if we expect them to, we rob ourselves of the chance to have them continuously improve their stories.  I do not mean to single out the Times, which is one of the most scrupulous newsrooms around when it comes to corrections. Practices are in a state of flux today. News organizations don't want to append elaborate correction notices each time they make a small adjustment to a story. And if we expect them to, we rob ourselves of the chance to have them continuously improve their stories.
[I'm adding some text right here that I'm going to delete in a minute, just to provide an illustration of some versioning in action on this post...]  
The versioning solution takes care of all of this. It frees writers and editors to keep making their work better, without seeming to be pulling a fast one on their readers. It's a simple, concrete way to get beyond the old print-borne notion of news stories as immutable text. It moves us one decent-sized step toward the possibilities the Web opens up for <a href="http:// www.niemanlab.org/2010/07/ wikileaks-and-continuity- what-if-we-had- a-news-outlet- exclusively-focused-on-follow- up-journalism/ ">"continuing stories,"</a> iterative news, and open-ended journalism. The versioning solution takes care of all of this. It frees writers and editors to keep making their work better, without seeming to be pulling a fast one on their readers. It's a simple, concrete way to get beyond the old print-borne notion of news stories as immutable text. It moves us one decent-sized step toward the possibilities the Web opens up for <a href="http:// www.niemanlab.org/2010/07/ wikileaks-and-continuity- what-if-we-had- a-news-outlet- exclusively-focused-on-follow- up-journalism/ ">"continuing stories,"</a> iterative news, and open-ended journalism.
<i>How the plugin happened:</i> I got some initial help from <a href="https:/ /singpolyma.net/">Stephen Paul Weber</a>, who responded to my initial request to modify the <a href="http:// wordpress.org/ extend/plugins/ post-revision- display/">existing "post revision display" plugin</a> so as to only list revisions made since publication. Weber modified the plugin for me soon thereafter (thank you!). Unfortunately, I failed to realize that that plugin, <a href="http:// www.darcynorman.net/wordpress/ post-revision- display/">created by D'Arcy Norman</a>, only provided access to version texts to site administrators, not regular site visitors. <i>How the plugin happened:</i> I got some initial help from <a href="https:/ /singpolyma.net/">Stephen Paul Weber</a>, who responded to my initial request to modify the <a href="http:// wordpress.org/ extend/plugins/ post-revision- display/">existing "post revision display" plugin</a> so as to only list revisions made since publication. Weber modified the plugin for me soon thereafter (thank you!). Unfortunately, I failed to realize that that plugin, <a href="http:// www.darcynorman.net/wordpress/ post-revision- display/">created by D'Arcy Norman</a>, only provided access to version texts to site administrators, not regular site visitors.
Scott Carpenter, the developer who'd originally pointed out the existing plugin to me, stepped up to the plate, helped me work up a short set of requirements for the plugin I wanted, and set to work to create it. <a href="http:// www.movingtofreedom.org/2010/ 07/30/wordpress- plugin-post- revision-and- diff-viewer/">Here's his full post on the subject,</a> along with the download link for the plugin. We went back and forth a few times. He thought of some issues I hadn't -- and took care of them. I kept adding new little requirements and he knocked them off one by one. I think we both view the end-product as still "experimentally usable" rather than a polished product, but it's working pretty well for me here.  Scott Carpenter, the developer who'd originally pointed out the existing plugin to me, stepped up to the plate, helped me work up a short set of requirements for the plugin I wanted, and set to work to create it. <a href="http:// www.movingtofreedom.org/2010/ 07/30/wordpress- plugin-post- revision-and- diff-viewer/">Here's his full post on the subject,</a> along with the download link for the plugin. We went back and forth a few times. He thought of some issues I hadn't -- and took care of them. I kept adding new little requirements and he knocked them off one by one. I think we both view the end-product as still "experimentally usable" rather than a polished product, but it's working pretty well for me here.
As the author of a whole book on why making software is hard, I'm always stunned when things go really fast and well, as they did here. Thanks for making this real, Scott!  As the author of a whole book on why making software is hard, I'm always stunned when things go really fast and well, as they did here. Thanks for making this real, Scott!
If you run WordPress and like the idea of showing your work, let us know how it goes. If you run WordPress and like the idea of showing your work, let us know how it goes.

Note: Spaces may be added to comparison text to allow better line wrapping.

Sign up for emails from Scott

Comments

  1. All my plugin does is expose the built-in WordPress functionality – if a person is logged in, they will have whatever access their user role allows. This could be tweaked with plugins like the Role Manager to grant view-revision privs to non-authors as well.

    Your version works much better, I think, in that it exposes the content of each revision without worrying about exposing ability to revert or edit. I may be switching over to this plugin :-)

  2. CarlosT

    This is good, but there are two revision tracking models I think it might be worthwhile for someone to attempt to emulate. The first is the Wikipedia model, where you select two revision and it displays the changes side by side, which makes it easy to compare. The other one, which I get the feeling is much harder to do, is Word’s Track Changes, which displays changes within the text. That would seem to me to be the most helpful way, because you’d see the changes in situ, and you’d have a better idea of what the story was like before and after.

  3. Hi, CarlosT. WordPress has a built-in revision comparison that is more like Wikipedia and looks very nice. (I made a note of it and where the code is, in my post.) I’d like to use that but have to figure out how to use it in the plugin.

  4. Thanks for an excellent idea and an excellent plugin in “Post Revision Display.” This idea is particularly popular in a section of the scientific community interested in open and transparent research, such as the Open Knowledge Foundation (http://okfn.org). I use wordpress to keep my research in an open lab notebook; an area where displaying revision history is already considered best practice, and for which reason many researchers have relied on wikis instead. (Notebook here: http://www.carlboettiger.info/research/lab-notebook)

    I’d be curious to hear if you know of other communities / uses of wordpress that have found this concept most useful.

Trackbacks

Post a comment