Thoughts in motion, annotated

In Knowledge Work as Craft Work (2002), Jim McGee wrote:

The journey from apprentice to master craftsman depends on the visibility of all aspects of craft work.

That was the inspiration for a talk I gave at the 2010 Traction User Group meeting, which focused on the theme of observable work. In the GitHub era we take for granted that we can craft software in the open, subjecting each iteration to highly granular analysis and discussion. Beautiful Code (2007) invited accomplished programmers to explain their thinking. I can imagine an annotated tour of GitHub repositories as the foundation of a future edition of that book.

I can also imagine crafting prose — and then explaining the process — in a similarly open and observable way. The enabling tools don’t exist but I’m writing this post in a way that I hope will suggest what they might be. The toolset I envision has two main ingredients: granular versioning and annotation. When I explored Federated Wiki last year, I got a glimpse of the sort of versioning that could usefully support analysis of prose craft. The atomic unit of versioning in FedWiki is the paragraph. In Thoughts in motion I created a plugin that revealed the history of each paragraph in a document. As writers we continually revise. The FedWiki plugin illustrated that process in a compelling way. The sequence of revisions to a paragraph recorded a sequence of decisions.

For an expert writer such decisions are often tacit. We apply rules that we’ve internalized. How might an expert writer bring those rules to the surface, reflect on them, and explain them to others? Granular version history is necessary but not sufficient. We also need a way to narrate our decisions. I think annotation of version history can help us tell that story. To test that intuition, I am recording a detailed history of this blog post as I write it. The experiment I have in mind: annotate that change history to explain — to myself and others — the choices I’ve made along the way.

Time passes…

OK, I’ve done the experiment here. It certainly explained some things to me about my own process. I doubt it’s generally useful as is, but I think the technique could become so in two ways. As a teacher, I might start with a demo essay, work through a series of revisions, and then annotate them to illustrate aspects of structure, word choice, clarity, and brevity. As a student I might work through my own essay in the same way, guided by progressive feedback (in the annotation layer) from the teacher. It looks promising to me, what do you think?

5 thoughts on “Thoughts in motion, annotated

  1. I tried something along these lines by revising a document on GitHub a few years ago:

    GitHub repo:


    Not sure those are helpful to you, necessarily, but just by way of saying that I think this is an interesting and valuable space to explore.

  2. thanks Jon -this is amazing. I agree about its use in teaching -it reminds me (though richer technically) Of an essay development demonstration through a progression of blog posts with comments. I don’t know if you remember Chris Bigum, an Australian ANT researcher who participated in one of Mike Caulfield’s fed wiki happenings. He had a paper in the Networked Learning Conference 2014 about Public Click Pedagogy. I think he would be really interested in this. Sorry I can’t give you a link but I’m writing this with a stylus on my phone at Lake Myvatn Iceland using pricy 3G data:) l will try to connect you 2 in a tweet,
    P.s. l wouldn’t want every edit of my writing to be visible but like the idea of a slightly greater level
    of granularity. Mind you, I started coding with pencil, eraser and coding sheets :)

    1. > l wouldn’t want every edit of my writing to be visible
      It was a humbling experience to be that open about my process! But also very revealing. I wouldn’t want that level of scrutiny always on, but it sure seems like an interesting diagnostic and pedagogical tool.

  3. Very interesting. The change history without the annotation wouldn’t be nearly as useful.

    It is also good to see that others revise their writing as much as I do. I sometimes despair of how long it takes me to write a few paragraphs, but Blaise Pascal’s words provide solace: “I am writing you a long letter because I don’t have the time to write you a short letter.”

  4. > It is also good to see that others revise their writing as much as I do.
    And that’s part of Jim McGee’s point. When we only see finished work, we fail to appreciate the process — and are unable to learn from it.

Leave a Reply