An interview with Jonathan Boccara
  • March 12th, 2019

Jonathan Boccara, Author of The Legacy Code Programmer's Toolbox: Practical skills for software professionals working with legacy code

1 H 39 MIN
In this Episode

Jonathan Boccara is the author of the Leanpub book The Legacy Code Programmer's Toolbox: Practical skills for software professionals working with legacy code. In this interview, Leanpub co-founder Len Epp talks with Jonathan about his background, the gruelling examination process for getting into the French Grandes écoles, how to make presentations with great visualizations, the psychological and practical challenges of dealing with legacy code in software, his book, and at the end, they talk a little bit about his experience as a self-published author.

This interview was recorded on February 12, 2019.

The full audio for the interview is here. You can subscribe to the Frontmatter podcast in iTunes or add the podcast URL directly.

This interview has been edited for conciseness and clarity.


The Legacy Code Programmer's Toolbox: Practical skills for software professionals working with legacy code by Jonathan Boccara

Len: Hi, I'm Len Epp from Leanpub, and in this episode of the Frontmatter podcast, I'll be interviewing Jonathan Boccara.

Based in Paris, Jonathan is a software developer and a popular conference speaker and blogger, who has a particular interest in making code "understandable to humans", as he puts it in his Leanpub bio.

You can read his Fluent C++ blog at, and you can follow him on Twitter @@JoBoccara. I recommend you check out one or two of his talks on YouTube; they're excellent.

Jonathan is the author of the recently published book, The Legacy Code Programmer's Toolbox: Practical skills for software professionals working with legacy code. The book is meant to help programmers code efficiently while working with existing code bases, which presents a particular set of challenges for professional developers.

As software continues to eat the world, how we deal with legacy code is becoming a more and more common and pressing issue, and Jonathan's book is a contribution to our efforts to address it.

In this interview, we're going to talk about Jonathan's background and career, professional interests, his talks and his book., and at the end, we'll talk a little bit about his experience self-publishing.

So, thank you Jonathan, for being on the Frontmatter Podcast.

Jonathan: Thank you for having me.

Len: I always like to start these interviews by asking people for their origin story. I was wondering if you could tell us a little bit about where you grew up and how you first became interested in computers and technology?

Jonathan: I grew up in Paris, France. Just to make it clear, I'm a professional software developer, I'm team lead of a software developers teram. How I got into that originally - when I was like 12 or something like that - I had never heard about programming. I didn't know what that was about. And one day, my cousin showed me his programmable calculator. That was a cool thing back then. It was like the end of the 90s. And he showed me his little game, like a text-based adventure game he had made with a calculator.

I remember the thing would ask for your name like "Hi, what's your name?" And you could type your name in. And then it would rise high, and it would say, "Hi, Jonathan. How are you? Do you want to start the game?" I was blown away. I asked my cousin, "You did that? You can do those things?" And he was like, "Yeah, and I can show you." So that was the first time I encountered programming at all.

I tried to do that, and I remember having a hard time understanding basic concepts like variables and that kind of thing. After a few days, it clicked. And then I heard you could do that also on a computer. I had a computer at home, so I installed whatever you needed back then to do programming. I started to do my own text-based old thing. I really got interested in that, and then I started to do games, but with graphical things, like 2D games. Nothing really fancy, but the kind of games a 12 or 13 year old guy likes to play. So that's how programming became a hobby for me.

Len: I have a question about what you studied in university. I checked out your LinkedIn profile while researching for this interview, and saw that you studied at the prestigious École des Ponts ParisTech, which traces its roots back to 1747 and is part of the Grandes écoles system in France. For those listening who might not be familiar with it, can you explain a little bit about how the Grandes écoles system works, and how they're different from normal French universities?

Jonathan: Sure. When you're finished, I think the equivalent of high school in America, when you're about 17 or 18, you've got a whole range of stuff you can do. What I did is called the prépa - it's a French word, like preparation classes. That lasted two years, where you do really intensive maths and physics, essentially. Well, you've got various flavors, but that's the gist of it.

Those two years, where you cram maths and physics, help you prepare for a national exam. There's a national ranking with this exam at the end of the two years. And depending on your ranking, you can choose what engineering school you can get into. It's a first rank, first served basis. So the best schools get taken by the people that have the highest rankings, and so on. That's the basic way that works.

And then the engineering school lasted three years. The really intensive part is the first two years, where you basically work all the time. I'm really happy to have done that. I wouldn't like to do it again, because you work so much. But it's within human reach. It's a difficult time - you sacrifice your free time for two years. But that lets you in a great school, if all goes well. And it also gives you really interesting skills, like analytical skills, and being able to learn and work - that's stuff you can use your whole life.

Len: I'm just really curious. Is it self-directed? Are you entirely on your own when you - ?

Jonathan: Oh, absolutely not.

Len: Okay.

Jonathan: No, it really looks like school. You've got a math teacher, a physics teacher, a chemistry teacher, even a French teacher. And you've got classes, just more intense.

Len: And what happens if you do poorly at the end of those two years?

Jonathan: Well, you've got a chance to do your second year one more time, and take the national exam again. Except that you don't start at the same ranking. You're a bit late, because you had one more year to prepare. So you have a slight disadvantage in terms of ranking, but you can make it up.

Len: This is actually just something I'm particularly interested in because I've never spoken to someone who's gone through it before, but I have read about it. What's the exam like? So - you've been studying intensely for two years, in a sense giving up two years of your youth, but also devoting two years of your youth to learning. And then you go to this incredibly important exam. How does that work out? Is there a center where everyone from the country goes, or is it regional?

Jonathan: It's regional. When I went was in Paris. It's quite early in the morning, and I remember that day there was mist all over the place. There were like hundreds of us walking towards the center. It was a bit like the Walking Dead, really - because it was so early in the morning, and everyone was a bit stressed out.

I think what you feel that day really depends on people. What I remember from it is, I wasn't that much stressed out. I mean, I had worked for it so much that [I understood what] was going to happen anyway. You've rehearsed for that like 100 times over. You've taken like 100 fake exams during the year. You're prepared, basically, so you just go and do your stuff and hope for the best. That was how I felt about it at least.

Len: It's really interesting. There's a parallel from Chinese history, of bureaucratic exams, that you might be aware of as well, where young men - I mean, it was gendered, of course, at that time in Medieval Chinese history - but young men from around the country would go to regional schools. And it was actually multiple days. I'm a bit surprised to learn that it's just a one day exam.

Jonathan: Oh, it's not, it's multiple days.

Len: Oh, okay.

Jonathan: Even multiple weeks, I think. Because it's not just one exam with one ranking. It was something like four or five rankings independent from each other, perhaps? You can take them all, and they all give access to a different set of schools.

Len: And how did it feel to succeed at the end of all that?

Jonathan: It's pretty cool.

Len: I imagine.

Jonathan: Yeah.

Len: This is a bit of a history question, but schools like the one you went to were set up to play an important role in sort of the fate of the country; in the case of your school, bridges and roads and things like that, originally. When did it start teaching computer science?

Jonathan: To be honest, I don't know. And to be even more honest, I didn't study computer science there.

The first year is about general engineering. You do a bit of computer science, but you also do mechanics and maths and probabilities, and even a bit of humanities. A bit of everything. And then in your last two years you can choose a major. I chose finance back then. But today, I'm in programming, and I use a lot of what I learned from that, those studies I made. What I use is the analytical skills, the ability to synthesize stuff, to explain it to people, and the ability to learn. And those three or four things are key - at least in the programming industry, which is the one I know. They're much more valuable than knowledge about a particular technology that was like hyped at the time, and that's outdated now. Do you know what I mean?

Len: Definitely. I've got some questions about how you got into teaching people and communicating to people to help them improve.

Before I go there - I just discovered before we started taping this interview that you spent some years in London. How did that come about?

Jonathan: I majored in finance back in my school. We have a gap year where you have to go abroad, work somewhere for a year. It's like an internship, but for a year, which is probably too long an internship. I went to London to finance, because London is the place, at least in Europe, to work in finance.

Len: For now.

Jonathan: Yeah, for now. Well, back then it was.

So I was working finance. I was on a trading desk in a big investment bank called Commerzbank, and I was doing pricing and all kind of things related to financial products. That's what I did in London.

Then I went back to school in Paris to finish my studies. I tried to continue finance a bit, a different kind of finance. What I was doing in London, was what you call "market finance". It's about the stocks and rates and shares, that kind of thing. And when I went out of school. I wanted to try another side of finance, which is called "corporate finance". It's quite like performing financial analysis of companies. To be precise, what I got into was performing analysis of companies that was going to be taken over. It's called "due diligence." You probably know about that, Len.

Len: Yeah, I did a lot of DD in my mergers and acquisitions days in London.

Jonathan: Right. So this particular job was in Paris - I'm sure it exists all over the world. And I already hated it, like every minute of it. What I didn't like in it was that - what was difficult, was the working environment. People were mean. You had to face like clients that would be really mean, and not interesting. And the actual job was not so challenging. It was just moving numbers around. That was at least my experience. I'm sure that you or someone else could have a completely different experience in that kind of job. That's what happened for me.

That made me realize that this is not the kind of challenge I was interested in. And then I moved to the programming industry, and I used the fact that I knew a bit about programming, because that was a hobby - and I was extremely motivated to learn. That's what really makes a difference in programming, again. And I also knew about the software that the company I got into, made. It was about market finance, so I knew my way around a bit.

But in the software industry, typically for most people I've spoken to - and from my experience - the challenge is in the work itself. Code is challenging. Code is complicated. You have to think hard to get code right. But the working environment, it's not where the difficulty lies. People tend to be laid back, and it's a nice place to work - usually. I think that you want your challenges to be in the task itself.

Len: Thanks very much for telling that story. That's really interesting. I didn't think I would be getting the chance today to talk to someone about what it's like to do due diligence. But for those listening, many people may have had the experience, for example, of buying a house. And before you buy the house you get the house assessed. Imagine you were buying a multi-billion dollar house. You have to do all kinds of things, like check out the insurance, check out the accounting history, check out the environmental situation, things like that.

If you're, for example, buying a company with property in Germany, you have to look for World War II ordnance. All of these things are always very intense. There's usually time pressure. There's a lot of money at stake, and there's a lot of big personalities.

But as Jonathan pointed out - once you've done it once or twice, even though it can be highly paid and seem, from the outside, even a little bit glamorous - the problem itself is actually solved. And you really are just, as Jonathan said, sort of moving numbers around and shuffling papers. It's funny you say that, because that's actually basically more or less the exact reason I got out investment banking, myself, after two and a half years.

I actually maybe was one of those guys myself, who's not quite so nice. I was fortunate to work in a company with very few assholes, but there was a lot of intensity, which I quite - euphemistically, I'm saying "intensity" - which I quite enjoyed. But the intellectual challenge fades, at least with respect to the straightforward aspect of what you're doing when you start. If you start rising in your career, then all kinds of things like, basically, stepping over other people to get ahead, style of challenges come your way. And those actually are genuinely difficult challenges, and they're complex and interesting to some people - but not to everybody.

Jonathan: Right.

Len: And if you don't find the stepping over other people to get ahead part of it interesting, once you've figured out the technical aspect of it, you can just get bored. And so yeah, your description of that experience really resonated with me

It's interesting that you talk about how your experience in financing informs your ability to communicate to people. I wanted to ask you, was there a particular moment when you developed an interest in helping people become better programmers, better at tackling the real challenges?

Jonathan: It doesn't happen in one day. I didn't wake up and run around trying to teach people. I think - my knowledge built over time. When you're a developer, you have to keep learning. It's something nice. Because, most developers like learning. You learn stuff about the language you're coding in. You learn stuff about design. You learn stuff about the domain of your application. You learn stuff all the time. It builds up.

At some point, I had a few things to share - I think there's really nothing special about that. I think every programmer has something to share. Even younger people, they probably have tips and tricks for other young people. And senior people have - obviously, a lot of things to share. So I had my share of things I could tell people, and hopefully help with. I wanted to spread those things around.

The thing is, I wasn't quite fond of traditional training. You know, the kind of training's where you go all day, or perhaps all week. It's really disturbing for your work day or work week.

But I'm not a really good audience. My attention span is fairly limited. Nothing pathological, but I just don't have such a big attention span. So I wanted to give away this knowledge, but in a way that would have been easy for me to attend, either because that wouldn't disturb so much of my day, or because it wasn't so long. So I came up with an idea, and I decided to use it to share whatever knowledge I had at that time.

This is what I proposed to my manager. I asked him if he was okay, if I would spend 10 minutes every day right in the office, to tell my colleagues a few things I knew about C++. Because I had read a couple of books about C++. And that's the language we were using. And it was okay to try it, and the first time, I told everyone I would do that.

On the first day, I would stand up and speak up. That was really awkward. Like someone's standing up, speaking up right in the middle of the open space, telling people things on the white board. I did it for 10 minutes, and asked for feedback, and people felt that it was okay. So we did it a second time the following day, and then a third time. And then we kept doing it for weeks and months and years, and I still do it today.

That's something that's become routine in our company, and I have the opportunity to speak about that at conferences or on social networka, or my blog, and I got the word out. Qe labeled that "Dailies," because it's something that happens on a daily basis.

People got into it in my company. I was doing C++ and someone stepped up and did Java, and someone stepped up and did databases, and so on and so forth. In other companies, they would do that too, and post that on social media or tell me about it. That's a very nice thing.

Now, to do that, at some point you may fear you don't have much to say, holding forth every day for years. Or that you don't have time to prepare, because for some periods of time you've got big projects, or whatever.

So we put together a system to avoid that. We broke down the sessions into monthly sessions. Like, I would do my daily C++ every day on a different sort of topic. It would be obviously a specific thing, because it would last for 10 minutes. Then the following day, we'd do something different. And so for a month, for three weeks - anywhere between 10 and 20 sessions, say - and then the following month, I would do the same thing, the same contents, in the office of another team. Because this is local.

The point of it is that all you do is spin a chair, look at the daily, and carry on with your day's works. So it's not disturbing for your day, that's the whole point of it. It's local in an office. And I would do same thing in the office next door, I mean for those who were interested. And then the next office and so on. You could have a rotating scheme over like six or seven months, which gives you a fair amount of time to prepare.

Now for people that don't have time to prepare at all, even for a month - I think there's an interesting mapping in terms of format between daily sessions and blog posts. A blog post is generally quite specific on a particular issue or theme, or whatever. And the amount of content you have in a blog post is typically what you can tell in about 10 minutes. So I found that blog posts are a good source of content for feeding dailies. I happen to have a blog as well, and I use the contents of my blog to feed my dailies.

But I also use the contents of other people to feed my dailies. And that's a win/win situation, because bloggers are all happy when their content is diffused, and the people that make the daily have content. And the people that listen to the daily, listen to new content.

Len: I'd like to ask you about your blog in just a second. But before that, I wanted to take the opportunity to ask you about a talk you've developed. While researching for this interview, I watched a YouTube video of a talk you created called 105 STL Algorithms in Less Than an Hour, which sounds impossible. But anyway, everybody should watch this talk, it's great.

In it, you present a really cool world map of C++ STL algorithms, and you have animations showing how the individual algorithms work.

I have to say, it's the best presentation I've ever seen, where the presenter is trying to teach something about programming. I've seen quite a few. I'm not a programmer myself, but I've seen quite a few researching other people for this podcast. And no disrespect to any of them, but Jonathan's presentation is something special.

I just wanted to ask you a little bit about how you went about creating that? How did you generate the animations of how algorithms work and what they're doing?

Jonathan: Thanks. To answer that direct question, I use Keynote, which is the equivalent of PowerPoint, but for Mac. And I use blender, which is business software that can make 3D animations.

Len: This will make sense to people who watch it, but there's a really interesting way of moving boxes around to show how data is being moved by different algorithms. Did you actually use Keynote to do that?

Jonathan: Yes.

Len: Wow, okay.

Jonathan: I just use Keynote. I use blender for, I don't actually remember - but the first time the map gets on screen, there's this effect that's sort of like Game of Thrones. But it's nowhere near the production level of the intro of Game of Thrones. But that's the spirit I wanted to give, even though I didn't get the same quality.

So, there's this world map which looks like a world map. There's mountains and valleys and the cities are the order of events of the standard library in C++.

Just to make it a bit clear, if you are not a programmer and are listening to this show,what we call an STL algorithm in C++ is a piece of code that can operate on a collection of things. One typical thing you want to do in a collection of things is to sort them by size or alphabetical order, or whatever. The order of events in C++ are pieces of code that can do such things. There happens to be 105 of them, which are available when you install C++.

The map has all the natural things, and the cities on that map are named after the order of events. So there's a city that's called "Sort," and one that's called "Partition."

And when the map comes in [to the presentation], there's this effect which I've created with blender. It's really not that hard to do. I didn't know blender before that, and i's my friends - to whom I'm very grateful - who taught me how to do that - to like have a camera that hovers over a plane, essentially, on which you place a texture, which is the image of the map. And so the thing goes around, a bit like Game of Thrones. So that's blender.

The rest of the talk is like you described, animations of boxes. Because I can see a collection as a set of blocks laid out next to each other. And if you want to sort them, for example, it would move around and get into those sorts of positions. I completed it with Keynote. Keynote is a quite powerful thing when it comes to animations.

Len: That's amazing. And just - again, for anyone listening - if sorting algorithms sounds boring and obscure, just watch Jonathan's talk. It won't be boring and it won't be obscure and it won't take that long. It really does explain these things very well.

Jonathan: One more thing about that map, to answer one of your questions about how this all came together for that presentation. There's this opinion that's around the C++ community. It's been around for years. I think it originated in Sean Parent's talk. Sean Parent's a famous C++ developer. He made it a few years back, and he explained how important it was to know what was in the STL algorithms. This talk went viral. I mean viral, within the proportion of the C++ community - but viral.

So everyone was aware of that, but there are quite a few of them, there's 105 of them. And we don't really know them. We know we should know them, but we don't know them. So that was my topic. Let's once and for all get into that and learn them all. That's how I came with the idea of that presentation.

Now, how I crafted it, I guess you can imagine that I didn't craft it from day one, the way it looks like today. It went through quite a few iterations. Although the actual iterations, and I don't think they matter at all - what I took away from that, and I think it's an interesting takeaway when it comes to making presentations - is the thought process that structured a presentation.

When you say the 105 order events, it looks like huge lists of code stuff. That's not something you want to look at, even if you're a programmer and you love code. That's not something you can digest. So the challenge was to make that big chunk of information - to present it in a way that would be easy to digest and to remember.

How I did that is I looked at them, one after the other, just to learn those I didn't know at the time. Then I classified them. I thought each one of them I would decide in which criteria it would belong. Those categories didn't really exist for me before that. For each one I would say, "This is like sorting, this is like finding, this is like -" whatever.

Then I had rough classifications for the order events. From that I could refine it, like perhaps shuffle them around, create new classes of order of events, and then have this big picture.

There are seven categories of order of events. Seven is easy to remember. Within these categories you had sub-categories like those order events, they relate to each other. You should think about them together, you should learn them together. I think that's the value of the presentation.

When you have this classified information, the challenge is to present this big picture, but not to hide the data. You want to present the actual data. You don't want to make something really simple for dummies. You want to present the actual data, but in the big picture form.

Then the rest is just the cool stuff, like the map, the realms, the arms - I draw arms, that's something that's really nice to do. That's the thing that makes it nice to watch. But the underlying thing is research of classifying things and presenting stuff with a big picture, and not hiding the data.

Len: Thanks for that explanation. It's an excellent presentation. You can tell it didn't happen overnight, and there was a great deal of work and iteration that went into it. But in the end it is very compelling.

Jonathan: Thanks.

Len: And it is quite an achievement to do with that subject matter. Which is also actually very important.

When did you start your blog, and who is it meant for?

Jonathan: I started my blog about two and a half years ago. It was in November, 2016. It's aimed at developers who want to make their code more expressive. The blog uses code examples in C++, even though sometimes it talks about stuff that could be applied in any one language.

On that blog, I publish two articles a week, on Tuesday and Friday. Every Tuesday, every Friday you've got a new post. The theme of the blog, writing more expressive code, I chose that because after a few years, I thought that this was the most important quality you want for your code.

When you start coding, the thing that matters is for your program to do what you want it to do. You're happy with that. But it happens that, to make a program do something, there's about 100 ways, 100 different pieces of code you can write. 100 different ways you can write your code to do that thing. And they're not all equally good. When you write a piece of code, then it's probably going to say - I mean if I'm going to try something just on the side, to try something you're going to throw it away afterwards - but if you write it and you're like, in a company, it's going to stay for a while, probably - hopefully your company is going to stay with this code. And you're going to go back to it; you're going to have to change it at some point. Because maybe there's a bug in it, or perhaps your client wants a new feature that's related to that piece of code.

Perhaps you are going to do it, or perhaps someone else is going to do it. The thing that makes work more efficient when it comes to programming - well, when it comes to actual code - is to make it so that someone who would reads it would understand it. That's what I call expressive. This is the biggest thing I try to do for my code.

There are a lot of ways to do that. It's not just one technique to make code expressive, although there are some overarching principles we talk about in the blog. But there are 100 ways, and particularly when you dig into the details of a particular language - say with C++. This is the theme of the blog, and every post is related somehow to that theme.

Len: Just before we move on to talk about your book, I have a question about one particular post that you wrote, about how you can use lessons from programming to optimize your day to day life. I thought it was really fun, and I was wondering if you could talk a little bit about it. You, write, for example, about iterating on your morning routine.

Jonathan: I'm going to start from the coding perspective, and then I'll move onto the real life perspective.

In programming, it happens sometimes that your program is not fast enough. It happens. To fix that, there is one technique that's really conventional - it's been there for years. It's to profile it, which means run it through a program that can count how much time the program spent in every instruction. Or every function.

In a program, like an industrial-sized program, there are like thousands, literally, or perhaps tens or hundreds of thousands of functions that get executed when you run your program. It can be less on smaller projects. And every one of them takes some time - it's really short, it's like in terms of milliseconds - or even less than that. But it all adds up. It can take seconds or minutes - and that gets too long. Sometimes even milliseconds are too long, depending on your industry. But it can add up and be too long. When you run this kind of analysis, you get a list of functions with their time, and they're sorted in descending order by the amount of time they took.

There is this principle, it's called "The 80/20 Rule". That's all over the place in programming or in other domains - I'm sure you've heard about it. I mean, I'm sure that if you have like more than five years of experience in any domain, you've probably heard about the 80/20 rule. It says that 20% of the causes trigger 80% of the consequences - that's one way of putting it.

And when it comes to software speed, it says that 20% of the code is responsible for 80% of the time. And some go as far saying it as 90/10. So, 10% of the code is responsible for 90% of the time. So, you want to aim for those 10%, and your profiler is going to sort your functions by descending order of time. Those big guys are going to stand out at the beginning. And you want to act on them - focus your efforts on those big guys.

What you don't want to do is go around and optimize everything. Because sometimes by optimizing for speed, you are damaging expressiveness. I'm not going to go into details because it's technical about why there's this relationship, but sometimes it happens. You want to sacrifice expressiveness only in places that matter, and you want to act on them.

To put it into a nutshell, you've got big responsible guys in your code that take time - and you want to aim at them to make at your program faster. That's the code side of things.

In my daily life, I noticed that I spent way too much time in the morning to get ready. It would take me like 40 to 50 minutes to get out of my home, and I'd basically just take a shower. So this is ridiculous. I felt I could save a really decent amount of time for every morning. Morning times matters, right? Because you can do stuff in the morning.

I wasn't sure exactly where to begin that with, where exactly I would waste time. I didn't have the feeling of wasting time at a particular point in my prep in the morning.

So I took a stopwatch and measured everything I would do for those 40 to 50 minutes. The time it took me to brush my teeth, or to dry up in the shower, or to get dressed, or to put on my shoes - or whatever I was doing in the morning. Then I put that into an Excel spreadsheet, sorted them by descending order for time, and then I could see like the big chunks of time I would spend in the morning. I tried to figure out how I could optimize those specifically, take actions - and now I get ready in like 25 minutes, which is about half of what it was before. 25 minutes every morning, that's a lot of value, you can imagine. That's one example. But I've got a few others.

Len: That's a great example. I've just got a flashback. I never was so systematic about it. But back in my days when I used to commute, in London actually, I remember optimizing my morning flow. And I remember one time, realizing that if my apple juice box was less than half full, I could just place it on the glass and walk away, and it would fill up the glass, and then the box would go down perfectly flat on the table. And so I could save the time of standing there over the glass and watching it pour, and use that time to do something else.

It was just because I hate mornings. I just hate mornings so much that it's like, I'm going to attack this problem.

Moving on to the subject of your book: for those listening who might not know, and for those who I guess might be triggered by it, you can skip this section - but what's legacy code?

Jonathan: So, everyone has a different definition of legacy code, but they all mean something bad.

The general gist of legacy code is existing code that's painful to work with. That's the general idea. My definition, because I wrote a book about that, so I had have a more precise definition - it's threefold.

First, it's code that's hard for you to understand. You stare at it and it takes you a while to figure out what it's supposed to be doing.

Second, it's code that you're not comfortable changing, because you feel you might break something, or because you need free time to figure out how to integrate a new thing into the existing stuff.

And third, it's code that you're somehow concerned with. It's code that you have to interact with in some way. You don't really care about code that's outside of your company, it's not legacy code as far as you're concerned, in my definition.

There are quite a few other definitions out there. There's a famous one from Michael Feathers, who is a really famous person in the software industry, and particularly when it comes to legacy code. Michael Feathers defines legacy code as code without tests. Because you can test code automatically. You can write code that tests code. So when you change your code, you can launch a program that's going test it for you, and assure you that it didn't break anything. That's Michael's definition. It's legacy code; it's code without tests.

There are quite a few other definitions out there. Some people feel like legacy code is the code that was there in the company before they got in. But yeah, essentially it's around the same thing. I hope that clarifies.

Len: It does. I'm just curious. Would Feathers's definition be kind of historically contingent, based on the idea that code used to be written without tests? And that it's only now that it's becoming more conventional to write tests along with code?

Jonathan: Well -

Len: I ask this from a position of ignorance, I really don't know.

Jonathan: I think, yeah, there's that, because I think we've become more aware of the necessity of testing, after we became of the necessity of programming. Although, speaking at the industry level, we test stuff. We've been doing that for quite a while. Testing, it's something that's around for decades, probably. But there's code that predates that as well.

But it's not completely correlated. You have code that's produced today, that doesn't have tests. And when I say test, I mean automatic test. Like, when you write your piece of code, it can be tested by a human on the day you release it, and it can be tested again at some point. But the tests I'm speaking of - well, the tests Michael is speaking of, as far as I understand it, are tests that run automatically. So there's code that gets produced every day, and that doesn't have that kind of test coverage.

The reason is that as surprising as it can sound, it's not something that's adopted by everyone. Like some people I've met, right? I go to conferences, I go to meetups, and I get to speak with people and they tell me about how it's like in their company. And there are some people, not necessarily technical people - perhaps managers, I don't know - that are not really fond of spending time testing. Because when you write a test, you're not actually delivering a new feature. Or you're not fixing a bug, but just writing something for the future. And investing in the future - for the future - doesn't pay off on day one, or very, very little. So you'd have to think a bit long term, even though it's not that long usually when a test pays off.

Some people have a hard time convincing the managers they should spend time doing tests. Also, if you are convinced, and your manager is convinced - that testing is a good thing, sometimes it's difficult to achieve. Because, to write a test, you have to write a program that's able to encompass the code you want to test. And sometimes, it happens - and that's particularly true in legacy code, typically - that some code is connected with other pieces of code you don't want in your test, because they're not related. And connected in a bad way, I should say, like tangled with other parts of the code. So isolating a piece of code can be challenging and time consuming, and sometimes that's a reasonable way you can't really write a test, or not easily.

Len: One of the things I really liked about your book was that you make managing your feelings, when you're faced with legacy code, the very first topic that you address. For those who might not know, what is it about legacy code that can make it so emotionally repulsive to programmers?

Jonathan: Well, the first thing is, if you start programming as a hobby, and that's the case for quite a lot of people - code in companies doesn't look like what you do on your side projects. Like if you write a game, a text-based adventure game, and you had your fun - professional code doesn't look like that. When you get in a code base of a company that's been there for, I don't know, like a few months or a few years - you’ve got this huge amount of code that's completely loaded with domain information that you need to somehow work with, right? And it really doesn't look like what you were doing when you were a student and you had your pet project, or your uni project. It was small and you had everything under control - and you would understand every part of it. That's I think the first thing that can make it a bit surprising.

It's not - it's not a bad thing, though. A\ll through the book, I think that one of the messages that I want to get across is that legacy code is not a fatality, if you know what I mean? It's something you can work with. But if you happen to have legacy code, there are a bunch of ways to work with it. And that's what I explain in the book. You can do fantastic things with legacy code, but you need to be prepared. You need to have tools to do that. And when you're just out of school and you've never heard about that, it can be a bit of a shock.

One thing that can make it frustrating to work with legacy code, is that it can be hard to understand - by definition, if you stick to the definition I gave earlier. And understanding is something that's quite rewarding in programming. If you don't understand, well it's not that rewarding. It can be a bit frustrating. What makes it hard to understand is that, like we said when we were talking about tests - is that sometimes you've got parts of code that are tangled together. So when you investigate one of them, it relates to something that can be a bit far away. So you need to understand, also, that remote part. And you need to somehow make all this fit in your head.

When there's a lot, it's challenging. You can take it as a challenge, or you can just be overwhelmed. That's one of the things that makes it emotional.

Also, there's this quite natural feeling. When you come across a code, and you think you see a flaw in it, you tend to think, "Well, the person who wrote it didn't know what they were doing," right? So they designed something poorly, and you have to bear the consequences today. That can also be a bit frustrating, although I think this is a completely wrong view, and you have to change your view to be able to work with legacy code.

Len: What can you do to manage your attitude and change your view, when you're sitting there facing something? Because I have had some similar experience with complicated financial modeling. I mean, there's a lot more to mergders and acquisitions than due diligence, and one of those things is dealing with all kinds of complicated modeling. I know what it's like to all of a sudden be in front of someone's messy work. And yeah, getting into the right attitude is tricky.

Jonathan: The first thing is to escape that primal attitude of judging the code, saying, "Oh, this is terrible. I would have done such a better job. And I don't understand anything, this is crap, and I need to get out of here." You need to escape this attitude. The reason is, if you think about rationally - and programmers are paid to think rationally, that's about our job - first of all, this code is what makes the application run. You can question its quality, but that's what pays your bills. Basically, that's why your clients like you. That's what makes the application exist. That's what made it develop in its first years, what made it grow, and allowed it to exist today - first of all.

But then, when you think that you would have done such a better job - it might be true, it might be true. Or, perhaps, you wouldn't.

Perhaps, the particular problem the person who wrote the code was trying to solve, is more complicated than meets the eye. And if you were to do it again - you would face the same difficulties that they did, and you would realize it was much harder than you thought it would. So maybe the person who wrote it, you can't really blame them. Or not blame them as much as you thought.

Now, the thing is, the most rational thing to think is that, this is the code out there. If you have to work with legacy code, you can't change it by snapping your fingers. You can either moan and cry all day, and not produce anything and get fired. Or you can make the most of it. And, like I said earlier, you can make a lot of things with it. You can make fantastic things with whatever code you get to work with, or pretty much, I think. That's at least my opinion.

So, the first thing - when you came in your first day, and something that you have to hold I think, for your whole career, is - do not complain unless you want to improve the code. And that your complaining is directed towards specific things you want to improve or you want to learn from. But otherwise - just complaining for the sake of it, it doesn't bring anything. And it will make you more depressed, if anything. What's even more dangerous is that it will make your neighbors more depressed, and particularly if they're younger.

I think that's something we need to realize. When you're in a company, you've been there, even one year - let alone five years or ten years - you are a model for the people next to you that are younger. Because they came in and they don't know what the culture's like. If it's their first job, they don't know what working is like - I mean in the professional sense of it. So they're going to watch you. And if you spend your day moaning, they're going to think it's okay to do that - and that's the only thing you can do, and they're going to moan as well. So when you complain you have a huge responsibility. It doesn't bring anything unless this is specifically to improve the code. And it can really be damaging. So, just don't do it, alright? Be rational. That's the first thing.

Now, once you've left that primal attitude, you need to find a way to work with the code. There are plenty of specific things to do. I go into the details in the book. But essentially, the attitude is to take ownership. At least that's my opinion. It's what my manager taught me fairly early on, in like\ my first year of professional programming. He taught me that when you have to work on a piece of code, you have to take ownership of it - even if you didn't write it yourself. Maybe that person wrote it 20 years ago. Now, this is your code. And that's your job to work with it - to improve it, to do whatever you can to make the most of it. Rhinking from that perspective makes you more responsible and empowers you to work with it in the most effective manner, I think. So yeah, the second thing is to take ownership.

Len: And you write about how you can actually use legacy code to improve your own programming skill?

Jonathan: Yes. that's the part where I say, "Don't complain unless you want to improve the code." If you find a piece of code that you don't like - and it happens quite often with code that you're like, "Meh, hmm, not sure this is the best code I've ever seen." or, "This is crap," or whatever - how you want to put it - what you can do is just walk past, and go to the next thing. Or another option, and I think it's much more interesting - is to think about, well why exactly? Why you don't like it. What's in it that makes it wrong? Or makes it of not good quality?

When you start thinking about it, surprisingly, sometimes the answer is not quite obvious. Sometimes you've got this feeling that, "Oh, I don't like this code." And when you look at it, you can't really point your finger at what's wrong exactly with it. And that requires a bit of thinking. You're decomposing it in your head, trying to locate what exactly gives you this feeling about what's wrong about it. At some point, you might actually find exactly what it is. Even if you just move on, you've learned something. You've learned what to pay attention to, and this is valuable. Because when you are going to write your own code afterwards, you will have that in mind.

This particular aspect of code quality, you're going to get it right, and the more time it took to dig it out - the more it means that you didn't know about it, and the more you learn. One option was to move on after learning that, but you can also improve it. That's called refactoring. That's a very common term in the programming industry. Refactoring means improving the quality of the code by keeping the application behavior constant. Once you've found what's wrong about that piece of code, you can choose to refactor it. You can't refactor everything, particularly if you work in a large code base and you have to make some choices. I'm not going to get into that right now, because there's a lot of things to consider, but that's what I talk about in one of the chapters of the book. But, imagine you've chosen to refactor that particular piece of code. So you've improved it. What's tempting to do is to move on - considering you've done a good job, you improved the quality of the code.

But what you can do before moving on, is think back about what exactly you improved. Why is the new piece of code better than then old one? Sometimes you can tell it's better just by looking at it, but once again - not really being able to pinpoint what's better. So you need to do the same kind of analysis. Just think about what changed and how it's better, so that you can use that in your future code.

The analogy I use for that kind of analysis is the vaccine. So the vaccine, in medicine, is something you get into your body - a very small quantity, or a harmless quantity of the disease. And your body spends some time deconstructing it, examining it, building antibodies, whatever - and stores that somewhere in its memory and remembers it. So that when you encounter the actual disease, your body recognizes it instantly and smashes it apart in no time.

I think this analogy holds for code, because after you've spent time analyzing this wrong piece of code in excruciating detail, and you've found what's wrong with it, and you remember it - when you encounter that same problem with an existing code, or when you're about to write a code, you're going to smash it apart in no time as well.

Len: I love that analogy. I think it's related to the concept of expressive code. Because expressive code leaves the memory behind of the problems that have been solved. Is that correct?

Jonathan: Yes, there's that too. There's quite a few things including this, yeah.

Len: You brought up before that sometimes it can be hard maybe to - I've interviewed people who've expressed a similar idea before, that convincing a manager that you should spend time testing can be difficult, because they're often like tapping their watch and they want forward progress. But as you also said, it actually doesn't always take that long before you realize that there was actually a lot of value in testing.

I just wanted to ask you specifically- you came up with the concept of the dailies, expressive code is important to you, and this vaccine analogy about preserving solutions for the future, it's all very important. I was wondering if you could talk a little bit about how that kind of knowledge can be spread throughout a team and remembered for the future, like our immune systems do with vaccines?

Jonathan: One of the options is through writing documentation. Generally, there's this trend amongst programmers that people don't like writing documentation. You like writing code - you choose that job because you love writing code, but writing documentation, that's not interesting. The thing is, I think there are various ways to write documentation. Some of them are boring and useless, indeed. And some of them are really useful for you and for the rest of the team

First of all, when you write about something, or even when you explain something already that works so well, you by some magic understand it better. Even though no one told you anything while you were explaining it, but the very fact of putting it together and structuring it, teaches you stuff. It makes you realize things. It makes you get the big picture view. It makes you realize that there are holes in your understanding and makes you dig deeper. So the very fact of writing is hopeful for yourself, and obviously for the team as well.

Now, there is good, useful, precious documentation, and there is boring, useless documentation. How can you do your documentation right? I think it has a lot to it, but one of the heuristics I found, is that you need to realize that writing documentation is not a moral obligation. You don't do it because it's a good thing. What follows out of that is, you shouldn't write documentation as if it were homework.

You shouldwrite your documentation as if you were explaining something to your past self. It really shows, when you read the document that you've written like if it was homework. It really shows and you don't want to read that, and that's just as boring to read as it was to write. But if you write something to your past self, then you have to be clear. You have to effective. Because your past self didn't know that, what you're writing about.

Now, about this specific format, if it's something very generic that you've discovered - if you've discovered, I don't know, something about class design, object-oriented programming - how to make your "if" statement look right, how to make your program faster - whatever, that's very generic. Then write it on a blog. Start your blog. Having a blog is pretty awesome. Writing to the world, and letting people know, and start discussions about what you've found.

Now, if it's specific to your company, what you've discovered - the first thing is to put it somewhere you can find it. Not on your MacBook, not on your computer. I think a good place to put it is next to the code. Code is usually stored in version repositories. With Git, for example - if you don't know about that, it doesn't matter. But if you know Git, you know what I'm talking about. Code is stored somewhere, and storing documentation next to the code makes it easy to find it, and makes it easier to make it not too much out of sync with code.

That's also an interesting thing to think about, how to make it not out of sync with code. Because that's one of the problems of documentation. People that don't like documentation have this problem with it, that they sometimes read documentation that's out of date. It's worse than having nothing, because it's misleading. It tells you information that's wrong. So, you need to find ways to write about something that's not going to get out of date, but that's still useful. There are a few examples of that. I could get into now, anyway, I talk about that in the book, in The Legacy Code Programmer's Toolbox.

Also, if you go further into that - like making code and documentation closer, what we do typically with code, is code reviews. A code review is after you've written the piece of code, you show it to everyone in your team - or to at least some people. Most versioning systems, Git or whatever, have this completely automatized. It's a process, it's really easy to do. And then you can show the code to people, and they can comment on your code saying, "Are you sure want to do that?" Or, "Isn't that a bug?" Or, "Maybe we can improve the quality of that new code?" That's what we do, a best practice of doing code.

You can do the same thing with documentation. You can send it around the team and ask for feedback. And people are going to say, "Are you sure this information is correct?" Or, even more importantly, "I don't quite understand what you're trying to say here. Could you clarify?" This helps make your writing clearer. And making it clear is tremendously important. Because if you want it to be read, it has to be readable. It has to be clear, because otherwise people are just not going to bother.

Now, there are quite a few other ways, apart from writing, that can spread knowledge. Dailies are a way, of course. But you can also do what I call knowledge showing in eager mode and lazy mode. That's another analogy with programming. An eager computation is a computation you make ahead of time, just in case someone needs it - and it's ready so that you don't spend time computing it when it's needed, so the application doesn't freeze or whatever. That's eager mode.

How you can apply it with documentation is to spread your knowledge before people need it. What you can do - I did that some with some of my teammates, and that was really great - is have somebody speak, make just a small meeting, just a team meeting, and have someone speak about what they know on a specific topic. Even though it's not something someone asks specifically, but that's just something they know and they had trouble perhaps understanding - or that they know it would be useful and that someone is going to come across it one day or the other. Then just make a small, informal presentation, nothing too fancy, just, "tell me what you know." I call that "eager," because you do that ahead of time.

Now, in programming, you have "eager mode" and "lazy mode". Lazy mode is doing the minimal amount of computation, and leaving the computation to the last moment - to compute just what is needed, and nothing more. This is the idea behind lazy computation. I think you do lazy documentation by knowing who to ask. The day you need this information, if ever you need it one day - you know who to ask. How do you know who to ask? Well, of course it comes with experience, you get to know people, you get to know what they work on.

But, you can speed up that process by having people actively telling what they know about. Without getting into details, without getting about explaining how things work - just saying, "I know about such and such topics, because I've worked on them," right? And you go around the table on team meetings. Everyone spend five seconds telling what they know about, about what they can speak about if needed.

There's the Agile methodology. There's the stand-up meeting, typically in the morning - where people on a team go and speak about what they do. It's not made for documentation, obviously, but that can be the side effect for lazy documentation. Because you hear about what everyone's doing, so you kind of have a basic idea about who would know what. I think it's still useful to have this active approach of expressing what you know about.

Len: Yes, the concept of documentation, for people who aren't into programming, might sound a little bit in the weeds-y, but the experience I've had talking to people on this podcast about things like documentation and these types of processes - the more serious the work they're doing and the more senior they get, the more these things start to matter.

I remember interviewing somebody who had at one point in his career been working for a very fast growing online gambling company, and he actually took out months and months to do proper documentation. It was extremely serious work and extremely important, because there was serious money at stake, in these second-by-second transactions happening all the time. He ended up being the chief software architect for a major British bank.

Anyway, there are people who don't like testing, there are people who don't like documentation. But in my experience, it's people who take those things seriously - for any young programmers listening, it's people who take those things seriously who maybe go far.

My last question about your book: you write that you love - maybe this is related to what I was just saying, or I hope it is - but, you write that you love doing code maintenance. That's not something that most people boast about. I was wondering if you could talk a little bit about why, why you love doing that?


Jonathan: Just to explain what that means - in case someone is listening and not sure what maintenance is. So, producing a piece of software, you go through about two phases. There's the time you develop it - it doesn't exist, and then it exists. That's the first phase, you produce it. And then it lives, and people use it, and people will go back to you because they want to change it. They want to change it because they've got bugs, for example. Or they want to change it because they want to add stuff.

The maintenance I was thinking about here, is like when you're fixing bugs. Like, a client goes back to you say, "This doesn't quite work properly, could you fix that for me please?" Generally, developers are not really fans of making maintenance. That can vary from person to person. It's a bit like documentation, but not as much. Documentation is, I think it's much more frowned upon, but maintenance is, yes, definitely not the number one activity.

I happen to quite like it, which may sound a bit weird. But why do I like it? It's because it's a bit like a game, really. You know that some part of the application is not working properly - I don't know, like something is not displayed at the right amount, or whatever. This can be either rewarding or frustrating. It depends on how you tackle the thing. The thing is that you have to find, in that huge amount of code, where exactly lies the source of that problem. And that can be quite a challenge.

If you just roam around and look at the code, and search for something that's wrong in the code that's related to that feature that's not working properly - it's a nightmare, really. It's like just wandering around in desperation. I think that's probably why people don't find it interesting. Now, if you have a process to locate the source of a bug, then you know it just becomes a matter of time. And there is a process - I'm not sure you've got the time right now to get into it, but it's in two of the chapters, actually of the book. I could go into it if you want but it's a bit long-ish.

Len: Maybe just briefly explain it, but we want people to be buying your book, so -

Jonathan: Right. Essentially, the first thing is not to look at the code. It sounds a bit weird because the problem is in the code. But you don't want to look at the code. You want to play around with the application. You want to somehow isolate the problem from the application perspective. You want to test around with some specific processes - yeah, I'm not going to get into those little details, but you want to play around with the application to find where exactly what sub-part of the sub-part of the big feature has the bug.

Then you go in the code, to that specific position, with a hypothesis in mind. Maybe this is the right place to look at. And you look at it - and if you made a good job producing the site of the problem, then you've got not so much you've got to look at - so that's like a huge amount of code you don't have to look at. And if you don't know that code, and if it's code that's hard to understand, that's just as much you've saved. And you take it, if it's the right hypothesis - and if it is then, cool - and if it's not then go back to the application, and change the parameters a bit, and so on.

When you have this approach, and you've done it enough times that it becomes second nature - maintenance is like a game, because you know it's just a matter of time before you really track down this source of the issue. Sometimes it's not the case. In very exceptional cases, there are other factors at play, more technical or whatever. But most of the cases I've encountered, this is how you want to be efficient. And that really makes the experience much faster and much more rewarding.

If we can like take a step back about what we've just said about maintenance, what we've just said about documentation - even what we've just said about legacy code, there are parts in the job of being a programmer that - people were doing finites [?]. Like maintenance, writing documentation, handling code that someone has wrote - well, these are not popular activities. But if you want to, like you say, go far, you have to embrace them because this is your job. You can't just do part of your job.

You can't just say, "Well, I like writing new code and that's it." There's no such job, alright? Programming has a full spectrum of activities that, in the end, contribute to make your product awesome. And you want to be part of the largest part you can. Even if this involves maintenance, and documentation, and reading code that you didn't write yourself - that's something you want to be excellent at, because that's your job, and that's what will get you far.

Len: It's really interesting to me that you talk about the part where you're using the app to isolate the problem as closely as you can as a game. Because that's actually personally how I approach it. With Leanpub, when we're sort of doing a big release, one of the steps near the end is like, "Len, go break it." As a non-programmer, I have to figure out conceptually, how can I make sure that it's not two problems, it's just one problem that I've isolated? And have I done all the other things to make sure that it is just this one problem and not something else?

It is very much like a game that actually is enjoyable. It's enjoyable for me, because I'm not the one who actually has to fix them. I'm just the one who gets to find them. But it is actually an enjoyable activity. And as you said earlier, the reason you're here in the first place is because there's some code out there that's working, at least a little bit. That's a good way to approach what you're doing, to start from that foundation.

Just moving on to the last part of the interview, where we talk about being an author and writing, I wanted to ask you how you found out about Leanpub and why you chose Leanpub as your platform?

Jonathan: I first heard about Leanpub because I heard about a book that's on Leanpub. That book is called Living Documentation. It's written by Cyrille Martraire. It's actually about writing code documentation. That's how I heard about you guys.

Now, when I decided to get into the project of writing a book and self-publish it, I looked around for different options, including Leanpub. I think I got quite good feedback about you guys, and quite terrible feedback about some of your competitors - really. Like, on forums - and I'm not trying to name names about your competitors here, but some people got emotional, with some of the other people out there.

So yeah, Leanpub looked fine. I can also answer that question after the fact. Like, now that I know Leanpub, would I advise my past self to choose it? One of the great things you guys have is your support. You've got a fantastic support. I was absolutely impressed. Like, whenever I had a problem - be that technical, about, I don't know, generating my PDF, or feedback about the platform or whatever - I would just shoot you an email, and you would answer within the day, or half the day, or even a few hours sometimes. One evening, just before the big release - I had kind of an emergency with my book. I think it was you Len, you answered like within, I don't know, half an hour, something like that - and solved the problem. That really matters in that moment, because this is like, a big moment and you don't want to screw that up. I want to thank you for that, by the way.

Len: Well thanks, I mean, the one thing I'll say is that we do try to have very good support. One of the things that I'm particularly sensitive to is that, when an author writes a book, it's a labor of love and time. It's based on things they've thought about a great deal, and they often have great hopes for what they're doing. I think this might be related to - I've talked to some people who got emotional about their experience with publishers and other platforms - and it comes from that same space.

What you're doing when you're writing a book, probably what you're doing is very - maybe it's more important to you even than it ought to be. But when it comes to launch time, and things like that - when you feel like you may have lost work or something like that, when you've just done a big chunk and something's not working - we're a small team, we're not always going to be there 24/7. But I can say personally, I don't care if it's like midnight and I've had a couple of beers, and I see that like an author is having a problem, I will personally try and help them. Because that's really important. It is a personal thing.

Johnathan: Yeah, it really, really shows. And yeah, I think it matters a lot.

What I also appreciate is your landing pages, because they're so simple. When you look at them - you've got the cover, and big size, and a bit of blurb. And you've got this cursor which I find really awesome. People can pay the price they want, basically. There's the suggested price, minimum price - and you can pay whatever you want, as long as it's at least the minimum price. I think that's really cool. That's a cool feature.

Len: Yeah, that in particular - for anyone who's listening who doesn't know, Leanpub has a variable pricing model. This means that an author sets a suggested price and a minimum price for their book, and then a potential customer can take their mouse and they can actually move this slider around. So they can take it from the suggested price and move it to the minimum price, or they can move it even higher.

One thing we've found after releasing that feature years ago, was that people would - because Leanpub pays such a high royalty rate, we can also show the "Author Earns" slider underneath the "what you're paying" slider. And people actually move the "Author Earns" slider. Sometimes that's actually more important to them than what they're actually paying in the end. They're like, "I want to make sure the author gets $10 or $20 or whatever it is out of this." I have this feeling that it really does change the relationship the customer has to what they're doing - in comparison to a normal commercial transaction.

Just a couple more questions about your book.

Is engaging directly with people who have already bought your book important to you? For example, getting feedback about things like typos?

Jonathan: Oh yeah, absolutely. In the very last section of my book, there's a getting feedback thing. I leave my email address and I welcome any piece of feedback about the book. I'm absolutely interested in chatting with people about the book, or about the topic of the book in general. I want to know my reader's problems, basically, with legacy code, to see if I can bring more, or perhaps adjust the book so that it's the most useful to them, and it really makes an impact in their daily life, working.

Len: This has been almost a feature length interview now, so I'm going to jump to my last question, which I always like to ask of authors. Which is - if there was one thing that we could fix for you on Leanpub, or one thing we could build for you, and we would do whatever you asked - what would you ask us to do?

Jonathan: Sure. A couple of things. Should I choose just one? Or can I say a couple?

Len: Please, go ahead.

Jonathan: Well, a few people have asked me about paper printing. Like, it would have been fantastic for them to choose either the PDF or the printed version of the book, and to have it delivered to them, a book. That would be perfect for them. Now, I realize this is probably hard to implement, if you're not Amazon or whatever. But at least, as a workaround, I know that you guys make available a PDF that's nicely formatted to go to Lulu or Amazon, or whatever - but it would be nice to have a very detailed, step-by-step basis for - as an author, how do I get my paper print version out? Which website do I go? How do I do that? Am I involving any storage or whatever? How much money would I get paid? Pretty detailed things, because we have no idea how I should do that, really. Should I do it myself? Should I organize the printing and give out copies to the people I meet in real life?

Or should I go on Amazon? How much money would I make on Amazon? Would I even be seen at all on Amazon? How do I do that, technically? On which website do I go? Where should I subscribe? There are like 1,000 questions I'm asking - and I have no idea, and to be honest, I'm not really interested in digging out for myself. I think if you make a tutorial, it could help hundreds of authors with just one document. So that would be my first suggestion.

The second one is, it relates to the Markua. Markua, for people that don't know, is a - correct me if I'm wrong - a specific flavor of Markdown. The Markdown is sort of a formatting language, like you can type text, and when you want like a, say a word to be bold, you surround it with two stars. For example, you'll write plain text, but you sort of embed the formatting information in it, so that's the gist of Markdown. Markua is a specific flavor of Markdown.

I had a bit of trouble really, getting everything right. Like, the images size and getting code in the text. And having line numbers or not line numbers. And then sometimes the thing would just not do what I would ask. So I didn't ask correctly, obviously. But I wish it were a bit simpler to format the book with Markua. And perhaps show tutorials. I mean, I know there's a super long page explaining the Markua thing. But I feel I could swear, I did exactly what was on the page, and for some reason it didn't just give that right result.

Len: Thanks for both of those pieces of feedback. When it comes to using Leanpub - something you've written on Leanpub, to then go and make print versions available - we do have a print-ready PDF, but we actually don't explain how to do it. We're just like, "Go to Lulu or go to Amazon." And we provide you with all the details of the things you'regoing to need, but we don't really place them in the context of a bigger story about what you're doing. So we give you everything you need, but we don't actually explain like, "why precisely is this here."

That's a really good suggestion, and I'll put it on my list of things to do, to make a post. In fact, probably even a better thing to do, would be in our next author newsletter, we'll just invite someone to write a guest post about their experience doing that. Because it's kind of hard-won knowledge when you've gone through it.

When it comes to Markua, Markua is not fully implemented yet, so it doesn't have a full proper manual, like old-time Leanpub-Flavored Markdown does. Right now, Markua is more like a technical specification, than a manual. And one day, we will have a manual that explains things - not in a sort of like, as though you were building your own Markua processor way. But as in a like, "I'm writing a book" kind of way. That should make it easier, when it comes to-- "I swear I did things exactly right" - I have that feeling as well, with all kinds of things. And hopefully, when we have a proper manual, rather than a specification - that will be less common an experience.

Jonathan: I understand. There's one last suggestion I wanted to make. It's about the online editor. On Leanpub, you can choose either to write your book online - on the website on Leanpub, there's a bit like kind of a WordPress thing. You've got the text field where you can type in your book. Or, you can write it on your own and upload it somewhere on the internet, like on a repository, like Bitbucket, for example. And there's another one - oh yeah, it's probably Github. And Leanpub somehow connect with this online repo and pulls out the book.

So about the online editor, initially I wanted to use that, because I thought it was all at the same place, and it would make things convenient, because all of the settings of your books had to be on the Leanpub website. I thought the book might have to be there as well. So, I went to that as well, at first. And I had to move away from it and go with the Bitbucket thing, because it doesn't handle versioning, so if I change something I lose - or at least I think I lose - what was there before. And that's a bit scary. In terms of UX, I think there are quite a few things you could do to make it more friendly. I don't think it's a good example, but I use WordPress on my blog, and I found their interface excellent. The old one. The newer one - Gutenberg is a catastrophe, in my opinion. But if you know the old one, it's awesome.

Len: Thanks for the straightforward feedback. It's a bit of a digression, but I have heard about Gutenberg being a catastrophe from people who use that to write their blogs.

Our in-browser editor - there are two. There's one called a Visual Editor, which is for people writing genre fiction, and I'm pretty sure that's probably not the one you're using. You're probably using the Markua one.

Jonathan: Yes.

Len: We intend to improve both of them, but in particular the Markua in-browser editor is something we know that we need to improve. There's so much room for UX improvement there.

With respect to versioning, every time you create a preview or publishing new version, we actually do save a version of your manuscript.

Jonathan: Oh, do you? Okay.

Len: If you go to your book's URL, and then like at Leanpub and "/versions," you'll see it. It's in the menu, also, when you're in your book tools.

We actually do save a version of your manuscript. But tyou need to download it and then look at it. So it's nothing like proper Git, or anything like that.

But, like I was saying before - being sensitive to how much authors can be afraid of losing work and stuff like that, w've got this Versions feature. Every time you create a preview or publish, we save a version of your manuscript for you, so that if all is lost, that is still there. That's internal to Leanpub, there's no diffing and stuff like that. But those manuscript versions are saved.

Jonathan: Cool.

Obviously, you don't have to say - but perhaps you may want to, I don't know - hide it altogether? Because, until it gets a better UX, for me, it was a not so good part of the experience. And when I moved away to Bitbucket, I felt much better. So now, you have to know how to use Bitbucket to be able to use it. I guess maybe you have authors that don't write about programming and are not familiar with it, but -

Len: Thanks for that. We really appreciate hearing about - people are often overly polite, and don't tell you about the bad parts of their experience. We know that part of Leanpub could use a lot of improvement, and that it's not the best. I think that just watching sort our statistics - more and more people over time are becoming familiar with services like GitHub and Bitbucket, and how powerful they are. And so most people actually, when they see that they've got an option to use Github and Bitbucket, they just kind of ignore our in-browser Markua editor. Like, if they want to write in plain text and learn a new markup - they're probably going to be sophisticated enough, or whatever, to be desiring to use something like Github and Bitbucket, anyway. Which is why we don't encounter this issue so often. I'm guessing, people just probably just don't try it.

Jonathan: So you mean that the online editor would be most useful for people that write novels?

Len: Yes so there's two online editors. There's the one that's where you write in plain text in Markua, and then there's another one where it's actually the WYSIWYG, what you see is what what you get editor.

Jonathan: Right, right.

Len: That one's mostly for novels - you can't even - you can't upload images in that mode. And that's very deliberate. It's like if you pick up a Dickens novel, probably - I mean well, actually that's probably a bad example, because a lot of them did have images. But if you pick up a conventional genre fiction novel, there's probably no pictures in it. There's probably no underlining in it. There might not even be any italics. There's just words in paragraphs. And so we made what we call a Visual Editor to be precisely for that experience.

Separate from that, in your browser, you can also write in plain text in Markua if you want to. But that's the one that you're describing that needs a lot of work. And that is on our list of things to do.

Jonathan: Right.

Len: Okay well, Jonathan, thank you very much for taking the time to do this, and so much time. I really appreciate that. We covered a lot of ground, which is very useful, but it's also, of course, very useful for us. One of the reasons Leanpub advances is because authors like you take the time to give us feedback like you did at the end of this interview, so we really appreciate that.

Jonathan: Sure.

Len: Thanks very much.

Jonathan: Thank you.

Len: Thanks. And thank, as always, to all of you for listening to this episode of the Leanpub Frontmatter Podcast. If you liked what you heard, please rate and review us on iTunes. And if you're interested in becoming a Leanpub author yourself, creating a book or a course, please go to and click on "Why Leanpub?”

Podcast info & credits
  • Published on March 12th, 2019
  • Interview by Len Epp on February 12th, 2019
  • Transcribed by Alys McDonough