Facilitating the Spread of Knowledge and Innovation in Professional Software Development

Write for InfoQ


Choose your language

InfoQ Homepage Interviews Kevlin on Writing

Kevlin on Writing


1. I am Michael Hunger from InfoQ and I am sitting here with Kevlin Henney who hosted the Software craftsmanship track today at QCon. Kevlin could you tell us a little bit of your background of what kinds of things you pursue these days?

I have a sort of broad background, I work for myself, I am based in the UK, but I have to travel around quite a bit. I do a bit of training, a bit of consultancy, a bit of writing, reviewing, so a mix of things. Focus of my interest tends be patterns, process, practice, programming, sort of across that more perhaps specific than technologies at the moment.


2. Regarding writing, is that one of your passions, to write?

It’s emerged. Say, 20 years ago I started writing articles because I was really interested in stuff and it was kind of something that I felt I was interested in communicating those at those levels. I sort of continued the article writing. I’ve since written a couple of books with Frank Bushman and Doug Schmidt on patterns, contributed to a couple of other books, edited a couple of publications and sort of continued that kind of writing. I’ve done various columns in the past, but I’ve also recently diverged a little bit from the technical path into the sort of nontechnical writing as well as a little bit of fiction here and there, so that has proven kind of interesting. So yes, writing whether it is code or slightly loose and natural language has always kind of been there at some level.


3. What would you say: how has this writing experience influenced you as a developer or your thinking or your working with people?

I think the writing experience has changed quite a few things. One of the key things that most people under-appreciate is how much software developers actually write in terms of non-code artifacts, and I am not talking about documentation, I am talking about things like the email. You often do the same thing every day, but if you want to get a little bit better you have to focus a little bit more. I found that when I was trying to communicate to simple online interactions, I noticed that I started changing the way that I wrote when I started writing more articles, I was changing the style of writing and in all of these cases the thing that really stood out was this idea of reflection and the fact that the word count is not your goal, not your productivity measure.

The principle act of writing anything is to revise, so that you demonstrate you understood what you are doing. The more I looked at code the more obvious it was that actually what we are trying to do with good code, well that is what separates adequate and poor code from code that is in some way brilliant and that speaks to you. The act of revision is the most common thing. Writing, I can’t remember which author to attribute this to, but "writing is rewriting", that is what it is about, this notion of embracing things like refactoring which still some people do reluctantly or only in the most modest sense, although sometimes that you actually need to forget refactoring , throw it out, rewrite it is actually a better solution. At a broader scale is this idea of continuously looking for that feedback to shape what you are working on because what you are working on is a demonstration of your understanding, it’s what you want to say.

When you start thinking of code as a demonstration of: "This is how I understand it, it’s a, this is a representation of my knowledge and how I want to speak to you about it", it casts it in a completely different light and that notion of just using it as a way of instructing the computer is a very bleak and a very flat view that really doesn’t help us build larger systems and systems that have longer lifetimes and systems that other people will also work on. So the more I worked on that it’s made me more sensitive to the ideas of feedback, the ideas of self improvement, how you offer feedback and this idea of somehow it’s always in a flux. It’s sometimes said in the arts that stories and poems and paintings are never finished, they are merely abandoned. We can probably do a little bit better than that in software, although it does sometimes feel like the abandonment is there.


4. When writing you are considering your target audience or when I want to convey my understanding to my fellow developers of the system that I am working on. What do you think, what should we taken into account when writing code with the means of having not us being the ones that read this code and work with that, but our fellow developers or us in 5 months?

You want to be seeing it through other eyes which is remarkably difficult and that notion of looking for tricks and techniques that give you the kind of feedback; I mean there is obviously the ones of jokes that people sort of say: "I don’t need comments in my code because my code is self documenting". Now self documentation is not a judgment that you, the author make, self documentation is a kind of property that others will confer on your code, they will look at it. To rank something as self documenting it’s not the self that can do that, there has to be somebody else for example. Returning to the code that you have written, particularly if you were immersed in something, if you are really into a piece of code you start diving quite deeply, you are exploring, your ideas are coming at a kind of rate that only caffeine can keep up with and perhaps personal hygiene and pizza can’t, and you’re diving into this and you feel satisfaction that you’ve solved the problem.

Brilliant, leave it, come back to it the next day because probably a longer way in trying to focus some much on achieving a solution you probably neglected a few other things. And that other idea of revision is to always be aware of: "What would I do when if I were to come back from this? If I would go away for a week, what would I feel like? If I would go away for 6 months what would I feel like?" and remember times that you have come back in the past: "Yes, there is actually evidence that I have not understood my own code, it’s not just other people whose code I may struggle to understand. There is evidence that I have not understood this. When you are working on a piece of code, one of the most common things that goes on is relearning. We look at a piece of code that is unfamiliar to us, whether it’s our own in the past or it’s something we just wrote, also something we’ve just started on that somebody else has written.

When we look at that we are thinking at how does this work and we investigate, we explore and we work it out, maybe we make some notes to ourselves like how it works, to sketch it out, you form a mental model. You are satisfied with it and now you can make the changes you are supposed to make. You are satisfied when you step back. This is all brilliant on a personal level, but the problem is you have not actually any indication for the next person. I am not just talking about commenting and say: "What are the obstacles? - Well I didn’t understand this. The variable was incorrectly named." Maybe instead of writing in my notebook that "I remember represents this concept" or even putting a comment in "This represents this concept", why don’t we change it so that that obstacle of understanding goes away. "I did not understand this block but it does these 3 things. Maybe if I extract these 3 things…", so in other words actually used it sort of active engagement because it is writing.

Instead of writing about the writing why don’t you write? It’s there, it’s a fluid medium in that sense but often we are very afraid of it because it’s fluid in one sense, it has very hard concrete outcome in another, but that idea of using these little loops and that little bit of extra self awareness: "Yes, I have done that myself, I have been the person whose code I have not understood, I have done things that others have come back to me and I found I am offering them the same explanations." If you get that moment I am always explaining this piece of code, "Why are other people so stupid, why don’t they get it? Wait a minute. Maybe if I am always explaining this code maybe the explanation should be in the code not outside of the code. Why am I needed to facilitate this?" And that level of self doubt and critical view is not something that necessarily comes easy, I would say to programmer, but actually to humans. It’s a human thing.


5. So it's also mainly about putting you in a context that allows you to self reflect, to cut down, to use for instance refactoring no just as a tool for learning but also for transporting what you’ve learned to the next reader?

It is that idea of using "I am communicating through the code." There of course not everything can go through the code but it’s surprising how much can when you think about it, what could I change to eliminate the need for explanation, to eliminate the obstacle of understanding that someone else, myself, might have.


7. Recently you also edited a book with quite a lot of contributors. It was "97 Things Every Programmer Should Know" by O’Reilly. How did you come to this book or how did it come to you?

The 97 things book is the third in a series, "97 Things", from O’Reilly and the first one was "97 Things Every Software Architect Should Know" and that was hatched on a list run by Bruce Eckel enterprise programming list and Richard Monson-Haefel was sort of fishing around for recommendations, what are the things that every architect should know. He was looking for things that he could use in a presentation and it became apparent rapidly that certainly there was a lot of wisdom to be tapped in this group, but also maybe these ideas went a little bit further and he started hatching this idea of a book project, sort of an open contribution project, perhaps starting with the people on the list, but very much sort of a wiki-based open start project. People would make contributions and so on.

And that idea got picked up, the "97 Things" branding came in with that and the 97 was selected for various pragmatic reasons and whimsical reasons as well and the idea then is that it went a little bit further and more people found out about that, made some contributions, that book was published. There was a project manager one, that was not perhaps as open in it's call to others, but still operated on a wiki. The "97 Things Every Programmer Should Know" actually started one summer when I was reflecting back on something I had to mention to a programmer and I was looking at a piece of code and I was thinking back: "That is one of those things that every programmer should know," - trigger word. I’ve been involved in the software architect project so actually maybe there is one for targeting programmers more directly and that followed on.

So we started it fairly soon after, to build up the idea, I sort of scoped out what I felt was appropriate and the approach that I wanted to take perhaps a little different to the previous books in the series. I was after a very broad level of participation and that kind of had the project hatched and then sort of driving that and then that had a crowd-sourced wisdom and in other sense we’ve got an open-source model in the sense that each person is making individual contributions. You are looking at the wisdom of the crowd at that level, but it’s not open source in the code sense, in the sense that the modules call other modules, these are all individual. You are looking at individual voices and you want to enhance that, but you are also looking at a cross section. It’s not for me to determine what people should contribute. I’d suggest to a couple of people: "This would be really cool" or "You give me some ideas", that would be really cool, but to get the voices of the people because anybody can sit down and probably come up with 97 things.

Programmers are not known for lacking opinions. So I say "Give me 97", you will give me 97 things. I can come with 97 things, anybody can come up with 97 things, but what is more interesting is if you take this cross section people are going to throw things at you that you never thought to include and they will do so and they will take things that you already know and do so and present it in ways that are novel and exciting. That kind of approach was very interesting. So I was very much trying to be sort of editor and project lead and stand back a bit from it rather than be an author.


8. How did you experience the actual creation process of the book? What were the highs and lows that you experienced doing this? How long did it take?

From the initial call throughout actually getting a physical book out, probably around a year I think. I am not exactly sure of the timescale, but I sort of ran it initially; it’s the idea of "Maybe we should have an incubation period" and I contacted a number of people who I knew would write well. An incubation period would set a fairly high mark rather thank just have a "fire-and-forget" approach. So the people come to the site and say: "This is quite useful" or I see the kinds of things people contributed to and that kind of sets a sort of tone. So I ran an incubation period and then I opened it up and when I opened it up I did an announcement through various media.

Actually Twitter was one of the most interesting ones and that got retweeted quite a lot and a number of people followed on from there, it got mentioned in a few blogs, I mentioned it at conferences and so on. So you’ve got this cross-section of a network effect and the whole point is you don’t know how long that is going to take, you can’t really write a plan. When it went public, it was public for about 3 months before we had a cutoff and the incubation period was a lot longer before that, but I wasn’t just looking. And there was something interesting from the publishers who said: "We are nearly at 97 things" and I said: "That is not how it's gonna work. What we are looking at is much more that 97 things, is enough that you can pull out good cross-section." If you hit 97 that is kind of stop, it’s like somebody is saying: "How long this journey is going to take?" "It will take about 2 hours to get from here to here". "Ok, so we’ll drive for 2 hours then stop".

That is not the way you do it. You are looking for a sort of a critical mass. You are not just sort of sitting going to "Here is 97 best things", you are looking for a cross-section, so actually some of the articles that were selected for the book, were brilliant. It’s not a judgment of quality it’s just the way they fit it together. And it just like this is a more reasonable expression. So it was interesting people are little bit slow initially in the incubation period but also a little bit latent trying to get certain things finished and I applied a number of techniques. I thought, first thing is rather generically talking to people, because I know from a personal experience I prefer when the editor communicates with me directly. I remember at O’Reilly, they said, isn’t that going to be quite intensive. At the end I was interacting individually with 100 different people and over nearly 170 articles, isn’t that quite intensive? Well yes it is, but certainly I think the quality of the articles improved, but also there is a different relationship. Having been on the author end of this, I appreciate that, I appreciate the conversation and the whole point is we are trying to produce something that is good.

So there is that notion of one-to-one attention rather than generic broadcast. It was also other techniques, and a whole bunch of other stuff I learned from software development, how do we measure out progress. A couple of the earlier projects, the previous two "97 Things" were surprised by how many items were incomplete, because when you’ve got it listed in a bullet list on a wiki page it looks like you’ve got a lot. You need to then dig in to them to discover so many place holders, it’s just a sentence there or a sketch of ideas but you don’t have an article, you don’t have a contribution there. So I thought "How do we do this elsewhere? What are the agile techniques I can bring to bear? What will make it visible?" This is "to do", "in progress" and "done"; I basically used that. Then later on I switch that slightly, I wanted to make sure I got as much of the editing debt out of the way, because I know that is always something that people underestimate.

But know I am going to gather all these things together, if you are doing a contribution space book, you are going to gather, you don’t just send them straight out. You want to make sure that they are edited. You don’t leave them until the last minute and then edit them, that is the whole point of interaction with the editors. So it turns out that from the time I did the cutoff to the time we made the selection only a few things needed to be visited. So I spread the cost of editing, so this whole early-and-often approach again, that is something that I a learned from a software development. It applies to writing, this kind of thing, or editing specifically. And so I used those techniques until you had a very visible sense of progress. It is kind of ironic that I noticed that a number of people who are known for their agile development were really bad at getting things out of the "in progress" stage.

That was sort of a deep irony of that something that applies in one quarter of their life and doesn’t apply in another and I am not going to mention any names on that, but it was interesting that there were plenty lurking in the "to do" and "in progress" which never made it to the final thing. But in terms of the lows and the highs, well there were more highs. Once it went public, there was a very high rate of incoming contributions. It’s very difficult to keep up with them. That was kind of good but then I suddenly realized we do need to bring the deadline forward because otherwise there is going to be more to deal with. One of the simple lows actually was, I didn’t get much spamming at the site at all and that was a good thing, but one of the little lows actually was having to make the selection of the final 97 because I could get out like 110-115 fairly quickly, but getting down bellow that, I was stuck at 99 for a while.

I guess the one item we don’t have in there is "Don’t hard code your constants" but 97 is hard coded in the series name and getting from 99 to 97 was really tough, I definitely needed to kind of go out for a long walk and come back and then make a decision. But apart from that now apparently my wife said that I didn't have that many lows. When I am editing a book I am significantly more pleasant than when I am writing a book, so I am going to take that as a positive thing.


9. But the book is still available on the Wiki page?

It is, absolutely. It’s all the stuff there including the stuff that didn’t make it into the book is there, everything is open, it’s available and that is going to continue and that is part of the understanding with the series. So it is genuinely open in that sense, it uses a creative commons attribution, so there is a very high level of trust on all parts, on me trusting that O’Reilly would do this and that it would stay there and they certainly did, they backed that up, actually revamped the site at some point soon. Trust on the point of people giving contributions and putting the time in and then trust some other people. There is that notion that actually what is probably done has raised the value of the book because the book obviously is a different medium to reading a web page and in fact e-book sales has been pretty good which is interesting because actually reading an e-book is a different experience to reading a webpage itself.

There is a bunch of different stuff there, so yes, there are a lot of things that worked out and that kind of project is, it renews some kind of sense of positive feelings towards humanity because it actually it does work like that. You give stuff away, people are interested and you do find out, people do give you feedback and people are still interested in this other product that is made from it, the actual book itself, so that works out and didn't dent the sales.


10. What would you say is the thing you drew from the book that kind of influenced you or brought you something special other than the book creation process or the book itself?

It was fun to do. We’ve got 73 people, that is quite an achievement in that sense, getting 73 people to write something which you coordinate and it was a lot of fun and it’s nice that people are able to refer to it and there is a couple of frustrated authors in there who said: "I’ve been meaning to write a book, but never had anything published but now I’ve actually got something published." So that had been quite gratifying. A couple of people thanked me for the effort which at a personal level is always nice, but it’s quite nice to be able to do this and sort of: "Look, here is all this great stuff that people have done. This is a really nice article." I don’t know, this is quite nice little act of creation that sense that you can say: "I was involved in that" and I think the fact we used lots of photographs that are quite nice that kind of brings out the personal touch in that sense.

Jun 02, 2011