Become a Creator today!Start creating today - Share your story with the world!
Start for free
00:00:00
00:00:01
When We Talk About Software (with Francesco Tisiot)
755 Plays1 year ago
Ever read a bad README? We all have, and most of the time, we’ve just moved right along. A programmer that can’t communicate their ideas will find no-one uses their software. And that’s true even outside of the open-source world. The best software doesn’t win - the best software _that people can understand_ wins. So how do we get better at communicating our code? What do we talk about when we talk about software?
Joining to discuss that question is a data-streaming expert and skilled communicator, Francesco Tisiot. Unusually, this episode is recorded on location, as we met up in the hallway of a recent tech conference.
Francesco on Twitter: https://twitter.com/FTisiot
Francesco on LinkedIn: https://www.linkedin.com/in/francescotisiot/
Kris on Twitter: https://twitter.com/krisajenkins
Kris on LinkedIn: https://www.linkedin.com/in/krisjenkins/
#podcast #podcasts #devrel #opensource #software #presentations
Recommended
Transcript
The Multifaceted Role of Programmers
00:00:00
Speaker
We wear a lot of hats as programmers. Obviously, there's the core skill, the one we're known for, which is we can speak to these infernal machines and get them to do what we want. But there's lots of auxiliary skills we must have as well. We are designers of systems, of repeatable engines. When things go wrong with those engines, we become diagnosticians or detectives sometimes.
00:00:26
Speaker
A big part of our job is simply as clarifiers of taking vague requirements and making them so specific even a computer can do them. But on top of all those skills, there's one we really need but we don't talk about as much. That's the ability to tell stories, to communicate to people, to explain to them why we're doing what we're doing and how they can benefit from it.
00:00:52
Speaker
You know this from experience, even if you haven't thought about it. You've read a really good readme and a really bad readme, and that good or bad difference can make or break you using the software, right? It's their ability to communicate the what and why of their software that makes it useful or useless.
00:01:12
Speaker
So that's the topic for this week's podcast. How can we get better at talking about our software?
Introducing Software Communication with Chris Jenkins
00:01:19
Speaker
And unusually and quite delightfully, we got to record this episode in person. I happened to cross paths at a conference in California with this week's guest, Francesco Tissio.
00:01:30
Speaker
And as you're about to hear, he counts his ability to talk about the software as the thing that's really separated his career, made it stand apart and made his career as a programmer actually really work for him. So let's get talking and tell that story. I'm your host, Chris Jenkins. This is Developer Voices. And today's voice is Francesco Tissier.
00:02:06
Speaker
Joining me live at the current 23EVE, I want to call it. We're here for the conference tomorrow. Is it Eve? Land? Midday? I don't really know what time is it now. I reckon the day before any event is event Eve. That's the way it works, right? Yeah. Christmas corner at that market. Anyway, Francesco Tussio. Hello. Good to see you. Coming in from Italy. Directly from Italy. Yeah, and have you adjusted to the time zone yet?
00:02:36
Speaker
I woke up at 4 a.m. this morning and I managed to work with all my European colleagues, too. Okay. We've got kids waking up early. Yes, and the interesting bit is that my kid didn't make me sleep the night before my first flight, so I had to wake up at 4 o'clock Italian time without sleeping the night before, then fly for like 14 hours and now not sleep for another couple of days, but it's okay.
00:03:03
Speaker
So you're vaguely oriented in your own skull at the moment. I'm in my own time zone. Right, good. It's good to own your own time zone. Time zones are a whole other topic we could spend a whole podcast on, because those turn out to be a lot trickier than people think. Yes.
The Importance of READMEs
00:03:18
Speaker
But there's another part of programming that faces every developer, as well as time zones, and that's readmes.
00:03:25
Speaker
Which I thought was a pretty simple, tell me what the project is about, tell me how to configure it. But we got talking and you've got a whole rabbit hole of thoughts on this. Yes, I believe riddmies are beautiful and tricky at the same time. It's kind of the entry point of people to what you have to share. Yeah. So it's your chance
00:03:54
Speaker
to tell a story to make people realize that there is something interesting in the piece of code which is behind the rhythmic.
00:04:02
Speaker
Yeah, yeah. Storytelling is a key word there. I often think as programmers, right? We don't think of ourselves as storytellers. And yet, in a way, everything we do is telling a story to a computer. We have structural storytelling skills, but when it comes to talking to humans, suddenly we, I don't know if we lose momentum or we get lost.
00:04:28
Speaker
I believe programmers like to tell stories to computers because it's easier to predict what computers will come back with. I would say easier is not always accurate, but it's easier 99% of the time. With humans the reaction can be way different. I believe if you get the analogy, well not if you get, I believe a good analogy is
00:04:58
Speaker
basically trying to program for all the different operating system OS device type in the world at once. Right. From scratch. Every human being has a different, slightly compatible operating system. Exactly. This is the beauty of trying to design for humans on top of designing from machines. Okay. Do you think
00:05:29
Speaker
Do you think that if we can bring a better sense... Okay, actually, let's go back before that. What storytelling skills do you need in a readme? Why does it even matter?
Storytelling and Audience Engagement
00:05:43
Speaker
So as I said, the readme is usually the first touch point of potentially new people interested to your project and your project. So what storytelling helps, helps you bridge the gap in different ways to the people. So maybe you have an advanced audience that knows already the problem space and says, I want a quick link to the code that makes everything run.
00:06:13
Speaker
Or maybe you have a less advanced person that arrives there and tries to understand, is this something that solves the problem that I have in my company? So you need to have a little bit of storytelling to be able to
00:06:29
Speaker
take back in a wide variety of people, maybe talking about the problem that you're trying to face, maybe talking in different ways, not only in text, but also maybe adding some visual that will help understanding the architecture or the flow, so you can make whatever beauty you are creating in the back also understandable and interesting on the front.
00:06:54
Speaker
Yeah, yeah, so your... Is it beauty? Is it clarity? Is it bringing the whole thing to life? It's a little bit of everything. I would say... Let's say that, you know, your cold, which is what you rate as beautiful, it's the entrance of your house.
00:07:22
Speaker
But then, in order to arrive to the house, you have a gate. And you have a path from the gate to the house. You read me, it's both those. Because it's the gate, so if you have, for example, a really high gate that is maybe something that nobody can
00:07:45
Speaker
and go on top and understand what's inside. Nobody will look at your house and understand it is interesting. If it's too low, maybe users more advanced would say, oh, it's a nice house, but there is no protection in front of it, so it's useless.
00:08:04
Speaker
And then once you enter the gate, or you find that the gate is interesting, there is the road taken to your house. And this is how you structure Dribny to make different parts of your code accessible. So as, for example, if you take, you know, let's take Kafka.
00:08:22
Speaker
If you have part of code that talks about producer, you send people there. If you have part that is talking about Kafka Connect, you send people there. So trying to build the path for all these various people to the part of the code that is interesting to them will make all the people that are coming to potentially to your house, see the benefit of your house, see that it's well structured so the gate is not too low, and also find immediately the path to the room or to the place where they have to go.
00:08:51
Speaker
Yeah, okay. So stretching that metaphor a little further, though, one of the problems, which you've already referred to, is people come to a project for different things. Some people want to get in the front entrance, which shows how do I actually just configure this thing and start using it. Some people go around the side because some people want to know if the house is in the right area they're looking for. And yet, read me, it's a one-dimensional structure. It goes from point A to point Z.
00:09:20
Speaker
How do you try and cater to everyone while having a very limited structure to talk to people? I believe that's an interesting and complex topic because it's about how do you write documentation in general. So trying to find all the use cases, try to optimize for all the use cases will make you end up with
00:09:51
Speaker
8,000 light rhythms that almost nobody will ever see. So I would say you probably will have to pick one entry point and then probably one of the things is divide and conquer. So you divide the use cases in a really initial stage and you have other parts of other rhythms that are going in deep into those use cases.
00:10:20
Speaker
The good thing about this is that also for information discoverability, if you split in multiple files with good headers, you make also this information findable from, for example, Google and other search engines.
00:10:35
Speaker
Are you saying we should probably be thinking about writing a readme for every persona coming into your project? Assuming you want it to be successful as a project? Well, it doesn't have everything at once. So don't say, okay, I start this project and then I have to write readme for 50 different personas. But I will say
00:10:57
Speaker
Also, the opposite thing is by writing a rhythmic, by identifying the personas, you also start reflecting about for which this stuff is useful and allows you to tailor your message to the people that you are trying to convince or trying to inform about your tool existing. Yeah.
Agile and User Empathy
00:11:18
Speaker
Yeah. I think that point of putting yourself in a user's shoes, that demand on programmers to have empathy is so important.
00:11:27
Speaker
It's one of those things, I think, it's one of the core things about Agile that we keep forgetting. Agile isn't about having a daily stand-up or a sprint. It's about things like putting programmers closer to users so they can understand their world.
00:11:44
Speaker
I've been in the consulting space for, I believe, 12 years of my career before becoming a developer advocate. And I believe that helped me a lot. Because I was doing, not programming or consulting in the programming space, I was doing business intelligence. That most of the time was talking with users
00:12:10
Speaker
or business users or high-level business people that they said, I need a dashboard that talks about ABC. And they were perfect in doing storytelling on the business side. But the tool that I was working on couldn't understand storytelling. It was a series of rules of showing this field or that field, performing this aggregation or that aggregation, filtering for this specific user or that specific user.
00:12:38
Speaker
So my job was kind of translation. Either I was translating business outcomes into rules, I was either implementing them or passing the ball to someone else they had to implement. I believe, going back to the university, I did computer science engineering at the university. I loved doing the university, but I found that at university there were people like 10 times smarter than me.
00:13:07
Speaker
There was matter when you put them in front of a computer. On the other side, what I like is to talk with people and stay close to a computer. And I found that this space is, for my lack, quite rare. Yeah, less well populated, that Venn diagram. Exactly. So I believe storytelling fits in here.
00:13:30
Speaker
You cannot work only with the computers. I know that a lot of us love to work with the computers, but the counterpart is always a human. So you need to bridge that gap between the beauty that you did and what problems are solving on the business side or on the human side.
00:13:47
Speaker
This really reminds me of something we had, Ben Gamble on the podcast recently, a colleague of yours. One of the things he picked up on was that, like, LLMs, modern AI stuff, is really good about bridging the gap between humans and computers. Do you think, and yet it feels like cheating if we ask chat GPT to write our read-me's, do you think there is a computer-leverageable angle to telling these stories?
AI's Role in Documentation Writing
00:14:18
Speaker
I would say that yes, to a certain point. So tools like Child GPT, I feel as of now, maybe in six months they will be way, way better than me. Maybe there are now, I just don't know, and I hope that my boss doesn't know soon. The thing is, I would say they are good starting point in a way that you can use them to discuss with them.
00:14:45
Speaker
I don't think you can expect immediately or in few iterations a perfect answer. But what you can say is, probably I have this idea of a problem. Can you try to write it?
00:14:59
Speaker
Specifically for people like me, I'm not a native English speaker or writer. Sometimes, chat GPT is useful because I have this idea. Can you write it in a better English that I could come up with? And that it's something that chat GPT and other tools can do perfectly.
00:15:17
Speaker
Yeah, yeah. But then from that, when I try to read me, I mean, at certain points, yes. As of now, it still requires some human to go and fix part of it. Yeah, yeah, that's true. I found it quite useful because it's almost like having a writing partner in the room, right? And maybe it's not the greatest writing partner you could imagine.
00:15:39
Speaker
But it is always on hand, and that helps again with the empathy, realizing that you're not really writing a readme, you're talking to someone. Yeah, I believe that that is always useful. It's interacting.
00:15:56
Speaker
Now, I prefer, by a lot, interaction with real people, but sometimes, also interacting with a tool, it's very handy, very quick, and gets you closer to your goal. It's not perfect, but I would argue that most of the time, none of the interaction between humans is perfect as well.
00:16:19
Speaker
So I would say it's a good hand that we can have in order to build our readme. Okay, so that's a help that's close to hand. Do you subscribe to any of these ideas, like there's a classic structural thing of like, why, what is it? Why, what, how, so what? Do you have any of those kinds of tricks up your sleeve?
00:16:48
Speaker
Well, that's a good structure because, for example, start with why. So I'm a big fan of trying to understand the why of something before just going and doing it. The why part is also there to, and I believe it's good to have this as first exercise because you make you realize if what you created is helping someone.
00:17:16
Speaker
helps you realize who is the potential people interested and that helps also drive in kind of the messaging, the wording, the examples that you are going to use. Then the what part? I believe it's the needle because a certain point you generate the interest or you make people realize that they may have a problem where you fit in and you are describing what's in for them.
00:17:46
Speaker
And then the latest bit was then what? Or then how was usually the next step. It's like how do you configure this thing? Exactly. So yeah, then you talk about how to create something that is usually standard and customized for the use case. And lastly, you basically
00:18:08
Speaker
draw a summary of everything and make this maybe example that you start drawing applicable to a wider audience. Do you think it's always, you say drawing, and I know you've experimented with like more visual and interactive ways of doing readmes.
Enhancing Documentation with Structure and Visuals
00:18:28
Speaker
Do you think, should we be looking outside of the linear narrative of text to live demo type stuff in our readmes?
00:18:40
Speaker
I would say that it's an interesting point because we are both in the developer advocacy space, so I feel that part of our job is to close the gap between users and technologies somehow.
00:18:57
Speaker
We don't do that, for example, for live coding, in two completely different ways. You and I mean. Yes. You and me. What you do is you do perfect live coding. I enjoy your session where you go there and say, okay, I need this, then I need that, and then I need that, and you write everything.
00:19:15
Speaker
I cannot do two things at the same time. I cannot write code and speak in English at the same time. So what I end up as, for example, pre-built Jupyter Notebooks. So in that case, what I do is the code is still there, but together with the code, I build also a story and also visuals that go along with the story.
00:19:39
Speaker
because that's the other part. Not everybody learns the same. Not everybody is interested in the same way. Not everybody feels that something is doable or interesting in the same way. So that's a trick that I started using and I feel it drives the message. You have to try to, again, optimize your piece of content to be accessible and to be interesting for a wide set of audience.
00:20:07
Speaker
Some people will just think, okay, show me the code. Other people will see, okay, what's the architecture behind it? And if you put that on visual, or if you have something like streaming that moves all the parts, if you see that flow, if you show that flow, that will make people interested.
00:20:25
Speaker
So part of your job is to not create like a lengthy paper that nobody will read, but at the same time try to attract with maybe slightly different techniques, audiences that will be interested or willing to learn in different methods. Right, so you're hitting those different ways people absorb information. Yeah. I'm trying to think what types there are because everyone knows their thing about visual learners and maybe
00:20:55
Speaker
Maybe I need to branch out into doing the audiobook versions of Read Me's for the people that were auditory learners. That's the thing, I would say, you know, for my current talk, I'm playing with videos.
00:21:10
Speaker
So I have videos in the background. I was thinking about playing with music as well, but then there is another talk from a colleague, Chris. Chris Egerton. Yes. And he is playing heavily with music. So I said I believe it to him. But again, it's about making stuff interesting and accessible.
00:21:30
Speaker
to different target, to different audiences. Someone that likes music might go straight to the other session, someone that, okay, is attracted by a video, could come to my session and find it interesting. Someone else that doesn't like moving parts behind the speaker will find my session disrupted, well, not interesting at all and will walk away after five minutes. It's always the risk of trying new things, trying new methods and understanding the feedback
00:22:00
Speaker
from the people and that's the other good part. If you ever read me, someone could open an issue that read me and say, oh, the image that you showed there, I don't really like it. It's not a constructive feedback. But maybe it's wrong because A, B, and C. Or maybe you have a long wall of text. Why don't you include
00:22:21
Speaker
an image to showcase what you are doing. So that's the other part. Since it's that visible, maybe people will open an issue to find it to increase the beauty or not the beauty, but the to make the read me be a little bit more interesting.
00:22:38
Speaker
Yeah, it makes me think that that's a nice advantage of readmes over conference talks, for instance. Yes. That it can become a conversation, because people can open pull requests and start interacting, whereas a conference talk is a more static thing. It is if you deliver only once. I try to deliver it multiple times a talk, because that's the other beauty of the talk. In my opinion, a talk is not a static piece. OK.
00:23:07
Speaker
you change the talk depending on who you're talking with and also depending on the feedback that you got from previous sessions. One thing that we do at Ivan is before any event,
00:23:19
Speaker
you do an internal rehearsals. Oh, do you do that formally? Yes. Well, for DevRel, we do every time. For other parts of the other departments, we suggest that everybody does it. And it's a great way because you get people from the DevRel team giving you the details of, okay, maybe you should change this text because it highlights a little bit better, or maybe you need to paste a little bit here because the structure of the talk will be better. And then you get
00:23:46
Speaker
A Flink engineer that tells you, if you do that from Flink 117, there is something that changes, but at least you have the complete picture. You have a complete feedback and allows you to make your talk a lot better. The other bit is you're adapted to the target audience.
00:24:08
Speaker
a session here about moving from batch to streaming. I'm giving it at a conference about streaming, so I need to go into the nitty-gritty details on how you do that. If on the other side I'm giving this talk to
00:24:22
Speaker
a database conference like a Postgres conference, because one of the examples is based on Postgres. I will go more into the details of what's relevant for the Postgres DBAs, for example. So you tune it depending on the audience. It's the same thing as your resume. You tune it depending on who you want to talk to. Yeah, yeah. So it's like you make it sound a lot more conversational than we usually think of programming as being.
The Power of Human Interaction
00:24:52
Speaker
I need to share sad reality here. Until now, let's say in a couple of years, if computers will take the world over, but as of now, you still need humans to interact, to create the business, to have your project to be successful.
00:25:15
Speaker
So if you need humans, you need some sort of interactions, and you need some sort of a dialogue. I would say the rhythm is the first part. The rhythm is your door to get people in. The more you create the good gate, the more people you will have to follow the path to your house.
00:25:40
Speaker
Yeah, it's funny, one of my most successful open source projects. I mean, I think it was good software, and it definitely solved a need, and that was why it was successful. But the README was mostly an argument of why the world needed it. And I found that of all the projects I've ever done, it got ported to the most different languages, because I think the most valuable asset in the whole project was the case for why they should be written.
00:26:07
Speaker
people in like JavaScript or other languages said well yeah I see this point we should make it. If you take this to kind of a similar subject I believe people were doing something like streaming since a while. Why Apache Kafka has been different? Because there was a story behind it.
00:26:31
Speaker
I would say, you know, why event streaming? Why doing stuff one by one for each event is needed? Why weren't people satisfied with running a batch every five seconds? It's about creating a story that managing that event by itself will open new use case, new doors for your business. I believe once you start,
00:26:58
Speaker
Understanding the stories, understanding the powerful message behind the story, you start buying into event streaming into tools like Apache Kafka. But before that, everybody was fine with like querying every two minutes on a database. Yeah.
Learning from Stories Across Fields
00:27:14
Speaker
Yeah. Because we don't think, we don't think of new ways to solve something without a story. We might think of slightly different solutions to the existing problems, but it's a story that convinces us to look at the problem a different way.
00:27:28
Speaker
Yes, I believe the stories, like I would say books are the way that most of the times you change your mind about a topic. The Read Me is basically your book. Most of the time, that's the other bit about LLMs and my feeling about LLMs as of now. They are really good at
00:27:58
Speaker
answering in different ways problems that have been already solved. I believe the creativity of completely new problem statements, maybe it's already there and I didn't discover it, but it's something that is still on humans.
00:28:16
Speaker
Yeah, I think you could see that in LLMs when after you've used them for a while, what they're saying, you can see the shapes of it, you can see the cliches and it's cliches that you can automate. And for that creativity, that saying something no one's heard before, that's still on humans, thankfully. Yes. Do you think there are places we can learn to do this better in or outside of the programming world?
00:28:44
Speaker
I believe there are... I enjoy reading storybooks, not only because I have two kids and I need to read storybooks, but also because it makes my brain go out of work and think about new words and new stuff. I love watching cartoons with them because...
00:29:04
Speaker
It makes my young kid come out again. I feel that there are good examples. There is a book about Apache Kafka with authors. Oh, gently down the stream. Yes. Like picking up those examples or also maybe picking up the examples of how new technologies have been described at the beginning.
00:29:29
Speaker
Like how was Google described at the beginning? How was Kafka described at the beginning? Trying to learn from this initial stage and the evolution of the message is something that could help you realize how to write your own message. Okay. So is that your retirement book project that you're going to write the origin of the great project? I hope that I can retire and just, you know, stay
00:29:55
Speaker
on a sandy beach in front of a sea. Maybe if I need to do something, have a bar at the beach that I can manage. I'm not planning to write. I believe that by the time my story will already be written.
00:30:09
Speaker
I was hoping you'd retire to an Italian villa near a vineyard. Well, I don't have a villa, I have an apartment, but it's near one of the most beautiful Italian vineyard zones, so I'm in a good place for that. I miss the sea because it's two and a half hours away, so that's my next.
00:30:29
Speaker
OK, let's do go. Well, you've got work to do before then.
Post-Conference Reflections and Recommendations
00:30:33
Speaker
Yep. But we do have wine to drink at the reception of this conference later, so we should start thinking about that. Yep, absolutely. Pleasure to talk to you. It's a pleasure for me to be hosted by you. Cheers, see you again. Bye-bye.
00:30:47
Speaker
Thank you, Francesco. I will see you at the next conference or at the next vineyard. That could work either way. Why aren't there tech conferences at vineyards? Is that a good idea? Has that got some hidden parts to it that could backfire? Could backfire. Maybe we shouldn't do conferences at vineyards.
00:31:04
Speaker
Anyway, I'm going to leave you with a book recommendation. It's my favourite book on programming that isn't about programming at all. It's by Stephen King. It's one of his very few non-fiction books and it's called On Writing. And it's all about why and how we write things for other people to read. It's really applicable to programming. I don't think Stephen King ever thought of programming when he was writing it. I'll put a link to that book in the show notes.
00:31:30
Speaker
As ever, if you've enjoyed this episode, please let me know, tell me that story, and maybe let someone else know. The like and share buttons are always right there for you, so go and click. And until next time, I've been your host, Chris Jenkins. This has been Developer Voices with Francesco Tisio. Thanks for listening.