Let's Recommon IT

Workshop the Pattern

Hear what works before you hear what's wrong.

Thread:
Design patterns
Level:
collective-choice, in the governance column
File:
wiki/patterns/workshop-the-pattern.md

draft

explained in Who decides what becomes a pattern?

Workshop the Pattern Sketch in perspective: a table on four legs with a hatched pattern card lying on it. In front of the table, one mannequin reader points at the card; behind it, a second reader leans over the card holding a pencil. To the right, apart from the table, the author stands with a hand cupped to one ear. The table and card are a pattern workshop, a new pattern set out to be read before it leaves draft; the card is the focus. The two readers are the solution's readers besides the author. The pointing reader says what works, which comes first; the reader with the pencil says what could be better, which comes second. The author standing apart and listening is the rule that the author listens first and asks questions only at the end. The metaphor: a pattern as a piece of work set on a bench for others to look over, while its maker steps back.
Fig. 10

Hear what works before you hear what’s wrong.

Context

A new or revised pattern has been proposed for a shared pattern language.

Problem

Review by a single approver checks format and facts, but not whether the pattern makes sense to someone who wasn’t there. Authors defend their drafts, reviewers fix wording, and patterns are merged without anyone finding out whether they read clearly to others.

Forces

  • Authors are closest to their own knowledge and least able to see what’s missing from the page.
  • The patterns community developed shepherding and writers’ workshops for this, and counts them among its meta-patterns (Iba, “Pattern Language 3.0”).
  • Discussion builds cooperation that unilateral decisions don’t (Covenants With and Without a Sword).
  • Workshops take time, and the project runs on volunteers.

Solution

Therefore, discuss each new pattern with at least two readers besides its author before it leaves draft, with the author listening first and the readers saying what works before what could be better.

Actions

  • Hold the workshop at a members’ meeting or in the pull request.
  • One reader summarizes the pattern in their own words. Then readers say what works, then what could be improved. The author asks questions at the end.
  • Optionally, an experienced writer shepherds the pattern with a few rounds of feedback before the workshop.
  • Record the changes in the pull request.

Consequences

  • Positive: patterns read clearly to people other than their author, and the group builds a shared vocabulary.
  • Negative: it’s slower, and it needs at least three people. Until the project has them, patterns stay in draft or are workshopped with outside readers.

Mark up this page on GitHub