Software craftsmanship through drawing manuals

“The key to writing good code is to be able to express your intention using a constrained language, made to be understandable first by a compiler, second by a human being.

In this hands-on, we will explore the difficulties of expressing a meaningful intention using only a pen and paper, without words.

As a team, you’ll be in charge of drawing the manual for a given task, trying to express what to do and how to do it with a limited set of tools.

We will discover how these constraints lead the process and which tools can be used to go around these limitations and express the intention despite the limited expressiveness of the used language.”

This is the description of a hands-on I played at NewsCraft conference last week. This article aims at giving you the keys to be able to play this hands-on within your team and the key lessons that can be learned during the process.

Objective

The main point of this workshop is to make people think about one fundamental rule of writing: you only write to be read. And, in the case of coding, there are two categories of readers. The first, and for many, the only, is the compiler. You write code to serve a purpose and to execute a given task. You have to assert constraints for this code to be understood by the compiler, and ultimately the machine that will execute it. These constraints depend on the language you write in, but ultimately this creates constraints on what you can express towards the second category of readers:  other fellow developers.

When you think about it, you’ve got only a few tools to express your intentions when writing code, which are mainly the variables and functions names and the global organization of your code. What are the key elements you have to take into account when writing code for it to be clear and understandable, not only to a compiler, but also to other human beings? That’s what this workshop aims at highlighting.

The key conclusions you will reach (with some variations) are the following:

• Don’t make any assumption about your readers. They can be from different culture, have a different set of skills or experience.
• There is no such thing as ‘too obvious’. While some facts may seem trivial to you, other people probably won’t feel the same way
• Pair or mob programing is good, because it forces you to take into account different point of views while writing and results in a clearer code. However, it fails short if only one person holds the keyboard all the time.
• We are biased by the way an existing system is presented to us.

The workshop

Participant are to be divided in teams of 3-5 people. Each team must have two sheets of paper (ideally, paperboard size) and one pen.

Each team is provided with a card containing an activity to draw. These activities must be obvious, everyday things. Here are some tried examples:

• Shopping for groceries
• Going to the toilets
• Washing the dishes
• Buying an adventure book
• Going to the movie theater
• Playing Tic Tac Toe
• Calling mom
• Ironing clothes
• Drawing a manual (this one is difficult)

The workshop is held in three rounds.

Round 1

Each team have 10 minutes to draw a manual for the provided activity. No words allowed (numbers are OK, but don’t tell them) is the only constraint.

Once the time is over, each drawing will be reviewed. Don’t mention the content of the card used. Let everyone guess. In the first round, the organizer throw (snarky) comments about the drawings at the teams, without letting them speak. Amongst the comment you can do, these one will almost always happen:

• Reading direction. Not everyone reads from top to bottom, left to right. Is the reading order made clear? Likewise, in a code base, where do you start reading? In which order is it preferable to dive into source code to be able to understand what it does?
• Gender bias. It’s funny how some cards (shopping for groceries or ironing clothes, for example) calls for a woman representation. While this is not really related to good coding practices (code is almost always neutral), it shows in tests and documentation. In this day and age, being aware of the need for equal representation is a must-have.
• Back to the origin of the word, when code patches where literally patches put upon cardboards, you’ll find them in the drawing. The question is: as you started fresh and had two sheets of paper, was it really necessary to patch your drawing? Why didn’t you start anew? Which leads to: why do you leave commented code or dead code in your codebase?
• How any people did hold the pen? In the majority of cases, the answer is one. Why?
• Choose one of the drawing, and don’t make any comment on it except “it’s good!”. This will be useful in the second round.

Round 2

Pass each drawing to the next table. Ensure they have a second clean sheet of paper ready. Each team now have 10 minutes to refactor and improve the drawing they were provided, without knowing what was really written on the original card.

And time for another round of review, where you will start asking question to the audience, in order to switch toward a more participating review. Once again, here are some remarks that are almost guaranteed to be possible:

• Remember the “It’s good!” drawing? High chance that there was a minimal refactoring on this one. This illustrate the bias we all have when a codebase is presented to us, as there is never a middle ground. It’s either “It’s fantastic” of “It’s utter crap”. And the opinion we were given has a great influence on the amount of criticism we will apply to our reading. Truth be told, most codebase stands somewhere in the middle, not that great but not crap either. Parts will need serious refactoring, yet nobody wants to do it because, well, theses are the crappy parts.
• Patches again, this time more than before. Since you highlighted defaults and possible improvements during the review, there will be things redone, probably by scratching the previous version and drawing anew in a blank space on the same sheet. Despite the fact that a second sheet of paper is available.
• Consensus over bold ideas. Did it happen that an idea was turn down because only one person didn’t agree?
• Start anew. It happens that a team use the second sheet and redraw everything. Would your first action when working on a codebase be to trash it and restart? Are you sure they kept all the ‘functionalities’ of the first version? Compare them side by side to see.

Round 3

Once again, pass each drawing to the next table. This time, each team will have only 1 minute to make a single improvement. Then they will have to stand up and explain what this improvement is and why did they choose this one.

Encourage other team to voice their ideas, would have they chosen the same improvement?

Finally, for each drawing, have the team that made the initial draw give their opinion about the final result.

Final words

Since you took note of the discussions during all three rounds, you can now conclude, based on the remarks made by the participants. This is better if it takes the form of an open discussion between all participants.

Sample

Here are the three drawings produced during the Newscraft workshop, along with the original card: