Unresolved Forces - Copyright Richard Fabian 2024

Learn to write well

This point comes up again and again in different guises. The value of a pattern is how well it communicates how to solve a problem in a context—how you resolve the forces. Well, there are the forces of wanting to resolve problems for others by suggesting patterns to guide them. To resolve these forces, we need to have a solution for how to best present patterns, which means growing as communicators.

Some forms of writing education are practical. Spelling and grammar are essential to not trip up the reader while they are reading. But beyond the kinds of errors a built-in spell-checker can find, there’s also the realm of automated style support. I’ve used a few of these tools over the years to help guide my writing, but I keep falling back to older techniques, such as reading the text aloud and using printed proofs. Whatever your solution, we know there won’t be one solution that suits everyone. Otherwise, there would be fewer books on how to write.

There are a huge number of books on how to write¹, and not all of them are on spelling and grammar. Some of my favourites that apply to pattern writing concentrate on style and content rather than polish. You might be surprised to learn that many of these books are on how to write better stories. The reason for this is my recurring observation that patterns are more effective when framed as stories.

Patterns have a setup, a problem, and an inciting incident. They have a journey through a sequence of steps. There is a goal at the end, possibly unknowable at the start. This is a story. When you have an anecdote from a problem you solved, it’s a story. A pattern is a parable of how people have resolved a situation in the past. It’s a lesson on how you might use this wisdom to save you from the same pain in the future.

There are books on how to do this. There are videos online on how to write better. Takashi Iba even collected a pattern language on presenting, covering many of these story-writing aspects in Presentation Patterns: A Pattern Language for Creative Presentations[PresentationP14]. Storytelling, presenting, and writing for a film or play are all connected methods to transfer a story to another person. They all share features.

I recommend learning how to make stories that capture the audience’s attention. I would select Made to Stick[Stick07] to give you the groundwork for any anecdote-style delivery. The book contains many examples, and my copy has a permanent bookmark at the end in the reference section for when I feel the need to tighten up a work.

For selecting and structuring, any work on outlining will do, but two different works come to mind. The book Outlining Your Novel[Outlining11] is a way to work through a story, digging deeper and deeper into the plot. This can work well for larger works, but knowing about the technique can speed up a shorter piece’s development. The second work is a collection of courses by Shani Raja. His courses concentrating on how to write with clarity, evocativeness, and simplicity are good. But his editing course teaches you what you need to know to turn an outline and a collection of notes into a tight article or book. Unfortunately for you, I did not study his material until this book was in the first draft state.

Engaging the audience is the key. One of the first things I watched on this subject was by Larry McEnerny². He believed no one came out of school knowing how to write. They needed to learn what writing was really for. He claimed students had been taught to write to prove they knew, not to convince, surprise, engage, or educate. This skill, which is vital in later life, was missing from the regular curricula, at least in science, technology, engineering, and maths education.

His recorded lectures on writing opened my eyes to the problem I faced. I had not considered my readers. I did not know why they should care. I had been so intent on writing out what was in my head that I had forgotten, no, never even considered, who I was writing for. As I learned this, internalised it, and began to practice writing with intent, I started to see problems with the books I read. Notably, most patterns I read while researching were written to explain a solution. They wrote about how someone solved a problem but did not describe why it mattered and to whom it might matter in the future.

Richard Gabriel was aware of this problem. He often wrote on the subject, even publishing the Writing Broadside[Broadside]. It’s an element of software development not often brought up, but the more we think about software as being a team effort, the more obvious it becomes that good technical writing is essential to the quality of long-term or large-scale projects. At that point, it should be considered a critical, even core skill of a software developer.