Co-Documentation Workshop for User Workflows (Wikidatacon 2017)

At the WikidataCon 2017 I organized a participatory design workshop on documenting and sharing Wikidata editing workflows. Here, I describe what we did. It should be sufficient information to organize such a workshop yourself. I used similar methods before, but this particular way is new, so if you try it, I am very interested in hearing about your experiences!

I scheduled the workshop to be about an hour long. If there would have been more time, 1:30 or 2h would have been better.

I brought the following materials:

  1. Felt pens, many black, some red, green, blue.
  2. Paper, A2 or A1, for each person 1 sheet + some spare ones (A3 works OKish, A0 or whatever I had was a bit unwieldy)
  3. Examples of workflows.

Participants also should bring (or have otherwise access to) whatever they need to demonstrate their workflows 1

demonstrating Wikidata-workflows on a laptop ((Jan Dittrich (WMDE) (, )

Image: demonstrating Wikidata-workflows on a laptop (By: Jan Dittrich (WMDE), Source, License: CC BY 4.0 )


The workshop began with a brief summary (“…document each others workflows, so that we can learn from each other and that they can be used to improve Wikidata’s usability and usefulness by people who design the interface for Wikidata, like me [Jan]…”) and showing the schedule:

  1. Introduction to method 10min
  2. Work in pairs:
    • 20 min documenting person A’s workflow
    • 20 min documenting person B’s workflow
  3. Wrap-Up 10min


I show examples of possible ways to document workflows. They are mostly lists, sometimes with bits of annotations, rarely an arrow or so. The examples help the participants to get an impression what they will create.

I also set a level of detail for the instructions. In my case that might be “The level of detail should be that you believe that a person with basic knowledge of Wikidata is able to replicate your workflow”. This can be important, since there can be people who leave out large parts assuming implicit expert knowledge on the side of the reader (“it is just one step! I work from a list [how is this list made?] and edit [how is the connection from the list? How is the editing done? What is changed?] the items!”) or participants can be very detailed, assuming a total outsider (“first, start your computer…”). No position on the spectrum is bad, just make sure the participants are roughly at the same.

Work in pairs

Now to some organization: Splitting participants in pairs. “Everyone with one’s neighbour” is fast, so is just assigning in the style of “you two, and you two…”.

I briefly explain to the participants that each person in the pair will take a particular role:

  • One participant in the pair is the demonstrator who shows and tells the workflow
  • The other participant is the documenter who writes down the workflow and asks questions to clarify.

You now may ask: “Why the group work? Could we not work in if everyone documents one’s own workflow?”

Work in pairs makes sense, because:

  • The demonstrator can actually demonstrate the actions instead of only remembering them
  • The documenter tries to comprehend the actions and is serving as a stand-in for the larger audience who needs to understand the workflow
  • The demonstrator can counter-check what was written down

While questions are asked, the written documentation and future result is a core part of the communication process and not an afterthought. I hope this raises its comprehensiveness.

Two participants next to each other and communicating; one on a computer, the other with a sheet of paper, writing notes. Image: participants work in pairs: The person on the left documents the workflow, the person on the right demonstrates it. Both persons can use the documentation for asking questions: The documenter if they are unsure how and if they should write down something, the demonstrator to help documenting and to voice any problems if they think the workflow is not reflected in the documentation. (by Jan Dittrich (WMDE), source, License: CC BY 4.0 )


Now, everything should be set-up and the participants can start with documenting!

While people work, I keep track of the time, take care that they have needed supplies, answer questions or document the workshop in photos and text if everything else runs smoothly.

Tell at least 5min before the slot ends; when the time is up remind to do the same again, but with changed roles.


Ideally, there is enough time for a “general peer review”: One person from the pair can visit the other participants documentations, the other person stays to answer questions and add clarifications to the document. This would take about 10min. This serves the same purposes as having the documenter/demonstrator split, but now the understanding-part of the documenter’s work is done by other participants, too, hopefully making the process more robust.

Whether doing a general peer review or not: Give people 5 min time to check both workflows for ease of understanding and to add clarifications.

In the workshop I did, I wanted to upload the workflows publicly so that the wider community could also benefit. I told before the workshop, and now again I want to do this, that I would do it under an open license and that:

  • They could opt out, by telling me or writing so on the paper
  • They could be anonymous or credited however they liked
  • If they want to be credited, I asked to write their role (documentation or demonstration) and their name on the paper.

This took another 5 min. After this, I asked for questions, but there were none.

documented workflow

Image:documented workflow, (By: Jan Dittrich (WMDE) Source[], License: CC BY 4.0 )

documented workflow Image: documented workflow (By: Jan Dittrich (WMDE), Source, License: CC BY 4.0 )


I was happy how well the concept worked, considering that I did not use it before. The next time, I would try to

  • give more clear examples (e.g. the results form this workshop!)
  • make the writing the names of who-documented and who-demonstrated easier, including an obvious way to opt-out and stay anonymous.

If you try this or an inspired-by-format, please share your experiences!

More images and even videos of the workshop at Wikimedia commons

Notes: * Addition on 2019-10-19: The method is similar to prompted reflections: Kensing, Finn. 1998. “Prompted Reflections: A Technique for Understanding Complex Work.” Interactions 5 (1): 7–15.

Creative Commons License
Co-Documentation Workshop for User Workflows (Wikidatacon 2017) by Jan Dittrich is licensed under a Creative Commons Attribution 4.0 International License.

  1. If the workflows need large machinery or are otherwise too unwieldly to demonstrate, you can do the method without the demonstration. It is less useful, but still more useful than e.g. not documenting at all.