- Tags:: [[📖 Extreme Programming Explained]], [[My engineering management principles, values, and practices]], [[Writing is thinking]] - Date:: [[2021-03-09]] Originally published in [Mercadona Tech's Medium](https://medium.com/mercadona-tech/extreme-programming-for-writers-ff553e66848e). ## Was XP right for me? One of the things I liked the most about starting to work for Mercadona Tech is that they identified themselves as an _eXtreme Programming_ team. That was interesting to me, but not so much because I was particularly keen on XP. An organization waving a methodology flag gives you a ton of info. It is the opposite of a red flag: - It shows that they have a clear framework on how they do things, and thus, a reference to make decisions (as opposed to the typical wishy-washy “Scrum-like” response of many companies in these matters). - It allows you to have an idea on how it is going to be working there and whether you will be a good fit. I took advantage of that and familiarized myself more with XP before entering. I grabbed the canonical bible on XP, [Extreme Programming Explained](https://www.oreilly.com/library/view/extreme-programming-explained/0321278658/), and [[📖 Extreme Programming Explained|wrote about it]] to assimilate it better. My impression was that it is certainly… extreme in some of its practices but well-founded. However… > _Me_: Hey, do you have anything against docstrings? There are none! > > _A crowd willing to break my legs_: Geez… we don´t really do docstrings… …I believed some aspects of XP were either debatable or I wasn´t entirely grasping their rationale by just going through Kent Beck’s book. My _manager/psychologist_ [Miquel](https://medium.com/@tobami) suggested it would be an interesting exercise to set up a debate with the engineering team on why we do what we do around these questions. And there I went, proposing an agenda for it: [XP: The Debate.](https://www.notion.so/XP-The-Debate-463644d3f7124105abe8c35ac62cdc84) A surprising thing about the debate was that.. there was no debate. I thought some of my questions were going to be controversial. Far from the truth: there seemed to be a unanimous voice in the answers. This could give you [cargo cult](https://en.wikipedia.org/wiki/Cargo_cult) vibes, but I can assure you it is not the case: it was pretty clear everybody understands and believes in the reasoning behind their principles. ## Worried about (the absence of) writing As I wrote this wrap-up article on the debate, I realized that the thing I worried about the most was what I believed was the XP view on written communication. I consider myself a writer, not because I have any artistic talent for it, but because I strongly believe in its power in helping me understand complex topics ([[Writing is thinking]]), and it seems that [Kent Beck sees value in writing too](https://medium.com/@kentbeck_7670/writing-a-book-47688825695e): > The real value of writing a book for me is just how hard I have to think about a topic. However, in _Extreme Programming Explained,_ he makes quite a strong case for oral communication over writing, and goes further to say: > **Written communication is inherently more wasteful** (…) it is a one-way communication. Conversation allows for clarification, immediate feedback, brainstorming together, and other things you can’t do with a document. Written communication tends to be taken as fact or rejected outright, neither of which is an invitation to increased communication (p. 23) I had A LOT to argue about that statement. So, in the context of XP but more specifically at Mercadona Tech, I wanted to understand what, when and how people are supposed to communicate with each other. Truth be told, I was wondering whether we were not a good match or if I was missing stuff that was making me less effective in my work as a software developer. > XP is an opportunity to test yourself, to be yourself, to realize that maybe you’ve been fine all along and just hanging with the wrong crowd. (Note to Programmers). ^12af05 **Have I been hanging with the wrong crowd?** ## Writing in XP: there is more than meets the eye ### Writing in code The main objective we should have when writing software is solving somebody´s problem. However, _change is the only constant in life_ (Heraclitus), which means _everything in software changes_ (Kent Beck): the problem to solve, our understanding of it, technology… We will need to change our code continually. What is the main thing we could do to make future changes easy? Making our code easier to understand. It is [where we spend the most time](https://blog.feenk.com/developers-spend-most-of-their-time-figuri-7aj1ocjhe765vvlln8qqbuhto/) nonetheless. With this in mind, I think almost everyone in software development agrees on some (rarely universal) truths about comments in code, and here there was no exception. We could quickly skip this part: - Comments about _what_ a code does are redundant. They do not improve understanding: the code and its tests already tell you what it is doing. In fact, what is programming if not expressing in excruciating detail what you want to happen? [[✍️ GPT-3 me va a quitar el trabajo, pero yo tengo que estar entrenando algoritmia de bajo nivel|AI won't steal our jobs yet]].  - The urge to add comments for the sake of clarity could be a code smell: it may mean our code is becoming more convoluted that what it needs to be. Instead of using comments, our efforts could be better spent finding a way to make it simpler. - Comments are risky. They can easily become outdated. That was my main use of docstrings and any other comment: to clarify the reasons behind non-evident decisions in the code. But, it turns out, yes, they are redundant too indeed. I was already inadvertently introducing that redundancy: such important info goes into version control commit messages. In fact, in Mercadona Tech, these messages link to these beautiful explanations in Pull Requests:  It is incredible how [great git commits](https://dhwthompson.com/2019/my-favourite-git-commit) and PRs can be as documentation. In addition: they are timestamped: you know for sure that it referred to a particular code state, there is no ambiguity. And how easy it is to retrieve that information when needed: whatever version control provider you use likely implements global search over code, commits, and pull requests. ### Writing in design ![[📖 The Design of Everyday Things#^886491]] From [[📖 The Design of Everyday Things]]. If designing is a treasure hunt, then writing is its cartography. Oral communication is really agile, but we are forgetful creatures, [there is a limit](https://en.wikipedia.org/wiki/Working_memory#Capacity) on how many elements we can hold in our heads at once. I told the team that I am so concerned about this, that when I am deeply arguing with my boyfriend, I end up using a blackboard to track our main discussion points.  *Me discussing something* In a regular day at Mercadona Tech, there is quite a good level of talk. Counter-intuitively, this is a good sign according to _Extreme Programming Explained_: > People evaluating XP teams should understand what an effective team looks like. This may differ from other teams they have seen. **For example, talking and working go together on an XP team. The hum of conversation is a sign of health. Silence is the sound of risk pilling up** (p. 79) And this is because it is precisely in those conversations were most of the design emerges: - Usually, you will work in increments so small that what you really have is microdesign in stages. And such design simply emerges from coding: designing, in this case, is refactoring in “[red, green, refactor” cycles of TDD](https://www.codecademy.com/articles/tdd-red-green-refactor). - Design emerges as a result of a collaborative process: pair programming. This [_slicing the elephant_ has been discussed more in depth by my colleague](https://medium.com/mercadona-tech/a-release-story-there-and-back-again-f1a3c30f1881) [Antonio Bustos](https://medium.com/u/d2f5e721bece?source=post_page-----ff553e66848e--------------------------------) So in this case the writing that I needed, the crystallization I was looking for… is code! [[🗣️ Writing software - DHH|Code is writing!]] That was my missing link. And what if this engineering effort cannot be expressed in tiny increments? What if we are looking at a particularly difficult effort? **Mob programming** is the answer then! And again, there, code and its pull requests are writing. Sometimes it is not obvious how to slice the elephant: it may require input from product managers, designers, and engineers. Isn’t there a need for written word support? Sure it does, but I was overlooking it: that information is summarized in **user stories!** Those are some more nice pieces of writing! Maps of the territory we are exploring. ## Could we do better?  _Designing Data-Intensive Applications (2017), by Martin Kleppmann_ I am at rest, then. In XP, there is way more writing than what it seemed, and without redundancy, thus, little probability of information becoming out of sync. However, we are talking about the end of the treasure hunt, the X where you need to dig. But a map is not only useful to mark where the treasure is once you found it. When you are still searching for it, you need to keep track of where you went, what was there, where you are headed now… especially if you are not on your own and you have to coordinate different search teams. In other words, how do we keep track of what we are discussing? That is, how do we organize the information that ends up in writing a user story, scheduling a mob programming session…? The bulk of these conversations are still ad-hoc meetings and/or conversations through **Slack** but that brings some problems, because they are unpredictable, synchronous and messy. These conversations may happen at any point in time, and if you want to join (and you’d likely want to), you pay quite the price: losing focus on whatever you were doing and not having much time to think beforehand about the topic under discussion. It is ok to think about the productivity of the group instead of individual productivity: > ...the whole organization is focused on overall throughput, not on micro-optimization. If everyone is trying to make sure his function is not seen as the constraint, no change will happen (…). The reward system and culture need to align with **overall throughput instead of individual productivity** for the change to stick. (Extreme Programming Explained, p. 88) but we may as well end with superficial contributions and a Tragedy of the Commons for attention: > Individuals making reasonable decisions for themselves insure a negative group outcome. An office worker’s life is dramatically easier, in the moment, if she can send messages that demand immediate responses from her colleagues. But **the cumulative effect of such constant, unstructured communication is cognitively harmful**: on the receiving end, the deluge of information and demands makes work unmanageable. ([[🗞 The Rise and Fall of Getting Things Done]]) In addition, the lack of structure makes it hard to visualize progress on the discussed topic(s). Divergence dominates the conversation, context becomes scattered and no wonder it becomes difficult to reach any conclusion. ## Asking writing for more: writing as a navigation log And that takes me to the initial sentence about writing from Kent Beck: > Written communication is inherently more wasteful (…) it is a one-way communication. **Conversation allows for clarification, immediate feedback, brainstorming together, and other things you can’t do with a document.** Written communication tends to be taken as fact or rejected outright, neither of which is an invitation to increased communication (Extreme Programming Explained, p. 23) - Could you image N people asking (live) for clarification about different things? - If a topic is complex enough: “immediate feedback” is likely to be “poor feedback”. - When was the last time that you were able to “brainstorm” out-of-the-blue? Writing will help us figure things out. We can use writing for making any creative process more efficient. We do have shared documents now! Of course we can have discussions about multiple parts of a document, in the very same document! If a problem is complex enough that it is worth discussing, why not giving it structure in time and space? In other words: - (Time) Publish an agenda of the discussion and leave enough time to the participants to build up their views. - (Space) **Circulate a pre-read shared document first** with context about the topic, where participants can comment. The famous [Amazon 6-pagers](https://www.linkedin.com/pulse/beauty-amazons-6-pager-brad-porter/) may be a bit overkill, but having a live document that is collaboratively updated will definitely do wonders for keeping the discussion context organized, and may even make a meeting unnecessary. It is by no means a wasted effort: this document could even be a draft of the document that is being built (e.g., a user story). Or if we are discussing a software implementation, agile or XP should not be used as excuses for not doing your design due diligence. > But the alternative to BDUF [Big Design Up Front] isn´t no design up front, it’s a Little Design Up Front (LDUF) or Enough Design Up Front (ENUF) (Extreme Programming Explained, p. 105). Some people, like [[Daniel Elk]], CEO of [[Spotify]], go further to even say this kind of meeting prep is [“the largest source of optimization for a company”.](https://www.theobservereffect.org/daniel.html) Thus, (the right) writing is perfectly compatible with XP, and there is already a good amount of writing in XP documented practices. Still, I believe we can benefit even more from writing, as the very battle-tested tool it is to support our collective thinking processes. And the best thing is that you can start practicing this on your own; no special measures or coordination required. Try it with your teams as I am currently doing with mine at Mercadona Tech and you'll be amazed by the clarity it brings.