How to wag a dog

Speaker 1: Well, thank you. Um thank you all, everyone. Uh I've got you after lunch so you're slowly digesting. Difficult slot. Um it's really amazing to be back here on this stage after all this time because we were supposed to be here more than two and a half years ago, and we couldn't be. But David and El and the T And the team managed to put something on and the following year when I was too exhausted and fed up by all the plague even to attend the conference They managed to put it on in for a second time. And finally we're here. So if that's an if you have any illustration of somebody who kept the fires burning while you had to be away and couldn't come back to where you belonged.

Speaker 1: That's it. So David, well, all the team just hope you're really enjoying this event and hope that when you think about in A year's time, five years time, ten years time, you'll think, oh we did the Django Con Europe in Porto and it was really good. So is it sound okay? It sounds like it's Tori? I just have to say nib I need to move around a lot. Okay, well um if it cuts out, give me a signal and we'll do something. Okay. Um Let me introduce myself. So I'm Daniele Procida, I work at Canonical now And that's how you can find me on Twitter. That that's canonical, not me.

Speaker 1: This is my life history. So uh I know that the Django core team is not really a thing anymore, but I'm really proud of having that I'm a longtime open source software contributor, a Python community organizer organizer. I've been involved in the African Python movement, which is really important to me. And I'm a lot of my work is in software. Documentation. Is this a problem for everybody by the way? Yeah. Um while they're bringing the equipment. I'm the author of the DiaTaxis documentation framework. Which has now been adopted amongst other things Python itself for its uh

Speaker 1: documentation. It's a way of um approaching documentation. Um So sadly I'll couldn't malfunction, so so is it all done? We'll see now. Okay. It's a way of approaching documentation that's Become a quite popular. I I think or in in the Netherlands. What else? Oh that's what I look like on television. And I'm hiring at Chronicle. Uh my de director of engineering I'm hiring for well, I'm not hiring for Python people, but we are. So Come and talk to me about that. I am hiring technical authors for documentation. A lot of them. Not technical writers, technical authors, because they will have

Speaker 1: Technical authority. They will be technical authorities in their domain. So if you're interested in documentation, come and talk to me. Anyway, we should hurry up and get going. So look, this is a a dog and its tail. And The dog and its tail provide us with a model of a relationship between concerns that's very important because a dog and a tail belong together. And not just together, but in a particular order. So the dog wags the tail, and that's the way things should be. The dog kind of comes first. Not that the tail is not important. A dog without a tail is a sad creature. But this relationship gives us quite a nice metaphor to work

Speaker 1: with. So perhaps we can say that this can apply to software and documentation, that documentation is to software As the a tale is to a dog, and we can keep this image to help us keep the the documentation and software in a healthy relationship. The software wags the documentation and not the other way around. And documentation is essential to it. Software without documentation is as sad as a dog without a tail And I think many serious-minded teams and organizations do think this way about their software and documentation, even if they're not explicit about it. It's an organic met an organic metaphor.

Speaker 1: And that's good because that organic metaphors often give us useful clues about what's healthy and not healthy. The tail wagging the dog is something that can't happen in nature. It's an inappropriate disordered arrangement of priorities in the world. And we have many of those disordered inappropriate uh arrangements or priorities and a lot of them in software too by the way. Um quite an excess. So I want to give you a couple of examples of dog wagging where we get the relationship wrong and we have problematic outcomes and distorted perspectives. uh of of the way things ought to be. So when I was 18 I visited my friend in Budapest and he took me out for a it was a hot August night, he took me out on the back of his motorbike

Speaker 1: And I was 18, so naturally for safety gear I was wearing shorts and a t-shirt. And I can't actually remember, but quite possibly I was also wearing flip-flops. So even by the standards of 18-year-olds, I could be really pretty stupid And I hadn't been a motorbike passenger before, but one thing I discovered was that although he was the pilot and I was the passenger, I could steer the motorbike just by leaning my weight. All I had to do was leave my weight and my friend would have to apply a corrective action because the bike was turning in the direction I wanted it to go. And he was pretty surprised the first couple of times But for the next forty-five minutes I spent I enjoyed exploring this power, whether he really wanted me to or not. So I was a tail wagging a dog, and that's what I mean by an inappropriate disordered arrangement of priorities.

Speaker 1: So I was pretty lucky not to lend end that summer holiday all those years ago being hosed off the asphalt by the Hungarian fire services, but I got away with it. So that's an err an example of a reversal of the proper order Here's another example of the reversal of the proper order. When I touch something, it's me that reaches out and grasps it. So feeling is an act that comes out of me, a power that comes out of me to touch something. My power goes out into the world and it lands on the objects that I feeled. And when I was a child, that's how seeing seemed To me as well, that seeing was something that, you know, a power that came out from my eyes and grasped things in the world. Something from me landed upon the world.

Speaker 1: And that's how humanity understood seeing too for a very long time. So there's a 17th century illustration of the internal fire from the eye. That's how Plato and Euclid described it, this internal fire that shone from the eyes. And philosophers wrestled with that question, trying to put together a coherent theory of How this fitted with what we know about how we in fact we see things. So for a very long time fit um Theories of vision that posited its power as some kind of force or fire emitted by the eye were a serious part of scientific discourt discourse. So I was really dismayed as a child, about six years old To discover from my childhood science box that in fact it's not the case, that my eyes are merely passive receivers

Speaker 1: of light that bounces off objects and falls on my eyes. So I felt downgraded, like a power had been Taken away from me. It wasn't like reaching out to touch things in the world. And I can still remember that feeling of disappointment. So it's not surprising that humanity hung on to this idea for so long. And it still hangs around in our popular culture, in our everyday thinking. So, you know, think about having the power to see through things. An idea of a superpower that goes back to the ancient Greeks, if not earlier. In the 20th century, we started calling it X-ray vision. Again, the idea of a power, of something, rays, a force, coming out of us. But if you think about it for a minute, you realize that the idea of being able to see through things is not compatible with the idea that light bounces off things and comes to us.

Speaker 1: Being able to see through things implies an internal fire. But even in 22, 2022, that's how many people understand their own power of vision. An internal fire, something emitted by the eyes. And you could say the naive vision of theory gets it wrong, gets the order of things wrong. They think it's the tail That is wagging the dog. They think the eyes are transmitters, but they're really only receivers. So one thing that's really noticeable about these dog-tail relationships is that people really they want to get them right. If you saw a tail wagging a dog, you would call a vet Yeah, or an exorcist or something. And if you saw a passenger on the back of a motorbike

Speaker 1: steering the bike, you'd keep your distance. And if somebody gave you a wrong theory or vision, you'd want to correct them. And What are we going to do when we find ourselves with these disordered relationships in documentation in software? So I think a good way to think about those maybe is to think about the relationship between Active and the passive, so that maybe producing a software product is more like an active creative business and producing documentation is more passive and interpretive. The work of Writing software is to bring something new into existence and of documentation to reflect it. Not that one is better. Or more important or valuable than the other, but that one comes first and the other follows in a relationship.

Speaker 1: So the motorbike pilot is meant to be steering, and the passenger should be responding fluidly and appropriately. But it's the passenger who responds and the pilot who creates the situation. I don't know if anybody here knows the Modern Lovers, Jonathan Richmond and the Modern Lovers on their first LP He says if I were g if he's going to go to the Museum of Fine Arts in Boston, what he really wants is to have a girlfriend to look at the paintings with. So first he's going to go to the room where they keep the Cézanne and he says But if I had by my side a girlfriend, then I could look through the paintings.

Speaker 1: I could look right through them. And I know where he means Because I've had that experience. Because I have a girlfriend and we go to museums to look at paintings. And more than anyone I've ever known, she has the power to see right through a painting. I was in the this is in the painting in the Lachenhal in Leiden in the in the Netherlands and we hadn't seen this before and she said oh I saw another painting by this artist in the Rijksmuseum in Amsterdam and I said, oh really? And it by the way it turned out she was she was right. You know, she didn't know this, but she recognized it. I said, how can how can you tell? She said, I can tell by the way he painted the dog from

Speaker 1: behind. And I said You recognize the painting fr the artist from that. And I shouldn't be surprised because I've had that experience with her many times. I go to a museum, she sees something she's never seen before And she recognizes a texture, a detail of the composition, the way a brush stroke is, a combination of colours. And she knows what she's looking at, even if she's never seen it before. So I look at the text on the wall beside the canvas to find out something about it. She just reads this off the painting somehow She sees the back of a dog in the painting and it's for her it's as recognizable as the artist's name. So It's impressive enough to read off facts or information, but it's also the meaning that she pulls out from there, whether it's you know a twenty

Speaker 1: uh an old Dutch master or a twentieth century uh watercolour. So it's a very transformative experience for me to go to a museum with her because then I that's what I got what Jonathan Richmond was pining for. He wanted a girlfriend to look at paintings with so he could really see them. So and and that's what I have. I say girlfriend, you know, it's been twenty-eight plus years and she's the mother of my children, but you know, like Jonathan Richmond The idea of having a girlfriend is still qu quite novel and nice for me, so um that's why I say girlfriend. Anyway, so she sees these paintings and she grasps what's inside them, she looks right through them, she has a real visual power. And that's interesting because

Speaker 1: where is this power of vision coming from? And I think the truth is that it is coming from her. It's a power being emanated by her. It's a kind of internal Fire that reaches out from her and lands on the things that she not merely looks at but actually sees. So I want to take back some of my earlier remarks about the relationship between what's active and creative and what's interpretive and passive, I want to challenge that idea altogether because I think that we have a lot of it wrong. If you want to understand a work of art A work of an artist, an art movement, the history of art.

Speaker 1: Who do you need to hear about that from? Well, I can tell you, not from the artist. Absolutely not. You need a critic, somebody who can see. The artists have the art in their face. You know that you might as well ask an ant to tell you about an a magnificent ant hill. The artists are not the ones who can explain what's in front of us all and give it meaning. I love artists for their art, not for their insights into their art. But for insights we have critics. We have a long, rich, illustrious tradition of art criticism that has been in permanent dialogue with art

Speaker 1: for centuries. And it's a really badly misunderstood discipline. Because, you know, we tend to get quite sniffy with critics whom we think are overstepping their mark. Um, if they think that they're tails that deserve to wag dogs. You know, not good enough to be artists, just good enough to be critics, mere reviewers. Maybe full of knowledge, but they're jaded and they lack spark and so on. They're poor things, they're one step behind the art. And I think this idea is wrong, really completely wrong, because the critics are the ones who are able to take something apart and help us see it and put it back together again right before our eyes. Criticism is part of art.

Speaker 1: The art doesn't come first or exist separately. The creation and the criticism come into being together. We couldn't have art without criticism. You just like you couldn't have art without artists. So that's an idea that I think we need to bury to shake off. The idea that there's a flow from the creator to the critic. I'd like to see us move away from it. You know, it we have this idea of the active and the passive, the software and the documentation, the tail and the dog, and it seems so right because we think of a flow from one to the other, from the documentation to the software, from the uh creator to the interpreter.

Speaker 1: Like cause and effect. And it seems to be right that it goes in that direction, but I think it's wrong. I think it's mistaken about art and I think it's mistaken about software and documentation. I think that if we want to really understand seeing then we have to go back to the ancient Greeks. Because I think that Plato got it right and physicists are wrong about vision. Because when you go to a museum, do you see colored marks and shapes on the wall? Well, okay, in one objective sense maybe you do That's not why you're there. You go to see paintings. When I see a painting, it's illuminated not by photophotons, but by my own understanding. by a kind of internal fire that comes out of me, without which there will be no painting worth looking at.

Speaker 1: The power reaches out from me to grasp the thing I'm looking at. It's the seer that makes the art possible. The art depends on me So I'm right now I'm standing out standing here, I'm looking at you and all these photons are smashing into my eyes at the speed of light. And Of course I see shapes and movement and so on, but I also see people in a place and with a meaning around them. What I see has meaning. And That's coming from me. You're all bathed in my internal fire right now. That's how I see you. Because I see an audience. So I think we should write rewrite the physics books, because I think they're wrong. I think that Plato and Euclid and the six-year-old me

Speaker 1: were all right. And so too with software and documentation. Let's rewrite that relationship of the documentation that merely responds to the software. I'm hiring right now four technical authors at Canonical. I've read about 800 applications and I wish them all well, but the ones that make my heart sink are the competent ones that humbly and meekly and passively place documentation at the service of software, of being the tail that is. Faithfully wagged by the dog. I don't want that. Documentation is part of a software product. So some code might exist without any documentation. But that's like saying that Marx on a wall can exist without a critic. It's it's m we're missing the point. There's no art without criticism, there's no product without documentation.

Speaker 1: And what's more, the criticism and the documentation They are part of the art and the product. They're part of its definition and meaning. Documentation is not The user's introduction to the product. Its job is not to represent the product faithfully. It's part of how what the product is for the user. To the extent that the documentation doesn't exist. The product literally doesn't exist. And it defines it not just for the user, but for the creators too, just like art criticism Is part of art. Art and criticism are in permanent dialogue with each other, I said earlier. They respond to each other. When I'm talking to you, I don't really know my own thoughts until I've said them out loud and heard them

Speaker 1: And how do you respond to them? Until we've had that dialogue. I don't even really understand what I'm thinking myself. And if you're a software author and you want to understand what your software is and what it means and what it's doing You need to have that dialogue with something or somebody. And the best way to do that is by documenting it. You become your own Critic in the dialogue with yourself. You'll be understounded what you learn about your software by documenting it. So writing documentation It's like being able to have a conversation about your product in which you're faced with a tenacious critic who misses nothing and refuses to be brushed off because that critic is you, yourself.

Speaker 1: And that's one reason. Oh, by the way, you know what I'm going to tell you now, this is worth the price of the conference alone. One reason why so many programmers don't like doing documentation is that they cannot stand the scrutiny of a tenacious critic. Not even when that critic is themselves. And one reason Why writing documentation is often so bad, it's usually because your software is bad. It's an unhealthy dog that can't wag its own tail. And often your software is allowed to be bad Because you are allowed to be an artist without a critic. Because your software is a dog without a tail

Speaker 1: good enough to wag it back So um you can steer a motorbike from the back even if you shouldn't. Don't recommend it. But you can I want to tell you one last dog wagging story. So before I joined Canonical, I worked for a company with a rather excellent product that should have been doing much better. uh commercially I mean and I was working at the intersection of documentation and community and technical support. So better than anybody in the company. I had a really strong sense of how that product was for our users and what it meant in their hands. And that was reinforced daily. And of course in all products always there's always gaps between how the product teams see the product and how the users see the product.

Speaker 1: And every reasonable organization puts in place uh puts in place processes of feedback and evaluation to try and improve that. And that's of course what we were doing. Um was taken seriously. Feedback between community and documentation and support and product development and it never seemed to add up to a real change in success however hard we worked and however seriously we took it. And all the documentation was done professionally, competently, completely, and that wasn't enough. And it took me a long time to realize that no amount of documentation work was going to address this. I worked on documentation, I wasn't in the steering teams, but I realised, I discovered, that even though I wasn't the pilot I could still steer the motorbike

Speaker 1: just with my weight. And that's what I started to do with our product. I became a more active interpreter of it. I started to choose directions in the documentation, which is where I expressed them, and users started to follow them, and the patterns of usage of the software changed. And those fed back back into the product. So I was able to add the user's weight to my own on the back of this motorbike. And if the users, if I wanted the users not to go somewhere, I would remove some handholds and signs And if I wanted to make something come alive, I'd put some oxygen onto it. So I could starve some parts of the product of oxygen through the documentation and feed oxygen to the others. And

Speaker 1: they came alive like that, as things do when you feed them with oxygen. And every single thing I did sitting on the back of that motorbike was out in the open. It was literally being documented And over a period of years I was not challenged once about this. I'd say, I've documented such and such like this now. And I might be asked, oh well, what about that other thing? No, I didn't do it And they say, Ah, okay. And then they went back to work. Nobody once said to me, No, you should you should have. Nobody ever challenged me about it. Sometimes they engage with the documentation. But now they were engaging with it on my terms because I had written the documentation. If they wanted to have an argument about it, they had to first go through the trouble of working through the documentation I'd written in order to have that conversation

Speaker 1: I guess it was too much like hard work or maybe they were just okay with it. I don't know. But nobody ever took me up on it, even though it was out there in public in front of them. on my terms and the product started to change, the way we described the product started to change, the way the users used it started to change, and we started to see the changes in interfaces in the code, the conversations we had with customers about it started to change. We started not having discussions in which we tried to explain the product, we'd find ourselves having discussions in which the customers were telling us about their ambitions for things they would do with the product. And that's when you see that happening, that's a real change in the way your users are seeing

Speaker 1: and uh what a change in what the product means for them. So I wagged a dog, and that's what we can and should be doing with documentation, and it's what You can be doing whether you're a programmer or or someone else because anybody can do this, all you need to do is look at your software and have the conversation about it that documentation enables, that dialogue. Not just look at things, but see them, see into them with your internal fire that gives them meaning and illuminates them. Because whoever you are, when you start doing this in that way, it is going to make not the documentation better, but the software better too.

Speaker 2: Thank you.