118. Why Writing Matters for Engineers

Speaker 1: Welcome to Codeish, an exploration into the lives of modern developers. Join us as we dive into topics like languages and frameworks, software architecture practices, and individual and team productivity, all tailored to developers and engineering leaders.

Ian Varley: Hello, my name is Ian Varley. I'm a principal architect at Salesforce, and I've got a couple of guests with me today to talk about communication skills. So, Laura and Wes, why don't you guys introduce yourselves?

Laura Fletcher: My name is Laura Fletcher. I'm a senior program manager for leadership development at Salesforce. And speaking of clear communication, I should point out that I am not an engineer of any kind, but have been an instructional designer for 15 years. And my thoughts on clear communication are that, no matter what kind of technical topic you're explaining, we're trying to move people towards a desired behavior, right? And so this tie in between instructional design and technical writing have a very close connection that way.

Ian Varley: Yeah. Awesome. And I'm sure we will get deep into the weeds on all of that. So, I'm looking forward to this conversation a lot. And Wes, why don't you introduce yourself as well?

Wesley Beary: My name is Wesley Beary. I am also at Salesforce as an architect of engineering culture and practices, and have more of an engineering background than Laura, certainly, but less and less engineering over time. And communications has become more and more central to getting my work done. So, it's definitely something that I think about, especially as I communicate with the engineers that I used to work with more closely as to how maybe we can go about doing our jobs better, how we can collaborate more effectively, all those kinds of things.

Ian Varley: Yeah. And I think that's the thing we'll probably come back to repeatedly today is, I think that is true for any kind of technical person doing any kind of technical stuff, that over time, you discover that more and more of what you're doing really hinges on communication rather than the deeper technical details of what you're doing. Obviously, whether you're a software engineer or a rocket scientist, first and foremost, you have to know what you're doing, right? You have to be able to do computer science or rocket science, but at least in my experience, and tell me if y'all have had the same experience, it seems like when things really go well overall, a huge component of that is the communication angle. You have to work with other people, and in order to work with other people, you have to have some shared mind share about what you're working on, and what your goals are, and what problems you're encountering are. And if you're not communicating well, that stuff will quickly become the dominant problem.

Laura Fletcher: Absolutely agree. I think what you said about having that shared mind share or mindset, it's like the only way to get there is to verbalize clearly what my position is and double-check, is that the same perception that everyone else has or is there incongruent somewhere? So, that would definitely be true for me.

Wesley Beary: Yeah. And I know in working on culture and practices, I spend a lot of time just checking in with engineers to see how they're doing and how things are going. And one of the things that has come up over and over again is that one of the things that people reach to when they think about their favorite times at work, it's almost always when they feel like they were working on something that tied into a broader narrative, right? That they understood what it is that they were doing, why it was important, what they were doing was going to lead ultimately to that important thing. And it can be easy to lose that even in the broader context of work. And so I think it really goes back to this notion that like, if you can communicate effectively and help people to understand what it is they're doing, the impact it will have, why it's important, why you're doing it the particular way you're doing it, will just lead to people being more satisfied with their work and more happy. So, that's also really important.

Ian Varley: I think that's so interesting. And it's funny, my experience at Salesforce has really mirrored that in that when I started, I was an engineer working on teams delivering software, and I kind of quickly noticed that exact effect that you're talking about. The fact that when everybody is kind of on the same page, when everybody is, I guess, working towards a common goal that they believe in and that they agree on, things go great, things move really fast. And when there's any kind of friction in that, when there's any kind of sand in the gears, they're about, oh, you have a slightly different perception of why we're doing this than I do. Or you think that our goal is X and I think that our goal is Y. That really just slows everything down. That makes everybody more hesitant and the amount of overhead in communication that you're spending just grows and grows and grows until it becomes the dominant factor in the equation.

Ian Varley: And so that's why I actually kind of went down the path that I did here at Salesforce. I moved from an engineering specific role to a role where most of the time I was trying to help people see eye to eye, and communicate better about what it is that they're doing to clarify, to simplify and to really get down to the heart of the matter. And so I've been doing that job here at Salesforce for about six years, and my team's called Architecture Strategy. And that's exactly what we do. We say, okay, well, here's the architecture. And let's see if we can agree on it, see it clearly. And of course in practice, most of the time that's writing, right? That's what I'm doing is writing, not code, but prose. And it does play a really important role is having those lines of communication, those lines of clarification open.

Laura Fletcher: Well, and I see you also curating a lot of communication, trying to highlight messages that should be seen across teams. And for the size of a company like Salesforce, even though teams are doing a lot of similar work and probably making a lot of similar mistakes, if we can highlight some of those mistakes or decisions, not necessarily mistakes, but decisions that have turned out to work really well or work really not well, so that we can save other teams the time of trying and failing, or trying and succeeding. Weeding out the try phase is a major benefit of kind of sharing this amount of information and being able to curate the right messages that are already clear enough on their own to have legs.

Ian Varley: So, I know that there are a bunch of different purposes that you can have in terms of like, if you're in a technical setting, you can be writing for a number of reasons. And there's lots of different styles, lots of nuance there. Wes, from your perspective, what are some of the dominant purposes that you think about when you think about communication and the styles that go along with that?

Wesley Beary: Sure. I mean, I think a really common one in the technical setting is basically to educate. You want to make sure that someone understands something, right? But often times I think what can be sort of intermingled with that, I guess, is when you're actually trying to convince somebody of something. Not just that you're trying to provide context and help them be on the same page as you, but that there could be a difference of opinions, and you're trying to convince them not only that they would understand what the different options are, but that they would agree with you, that the option you have chosen is the correct one. One tricky part with a lot of communications is those times when those sorts of things get intermingled, it's a lot easier to have an effective communication when there is a single goal that you can direct the entire communication towards. Instead of one where you're doing a little bit of this and a little bit of that. And I think that's one place where we can sometimes go awry a little bit.

Ian Varley: Yeah. Agreed. There's something we've been working on and you and I have been talking about it a lot here, Wes, is trying to up our game in terms of when it comes time to make a decision about something, how good can we get about clarifying the lead up to that decision and the ramifications of that decision, so everybody's making that decision the clear-headed way? And so there've been a few practices that we've actually been starting to adopt pretty heavily inside of Salesforce around that. And one of them is fairly simple and it's something called a decision record. And decision record is basically, Hey, when you have decided something, just write it down. I know it sounds so simple, but just write it down. Write down what you decided and maybe what were your reasons for making the decision that way, as opposed to another way? This is useful for a huge number of reasons, right?

Ian Varley: One of which being, if you come back later and you know, things are not going right, you can at least introspect why the decision was made a certain way, and maybe change your mind at that point if the facts have changed or if you realized you got something wrong. But at least you have a record of it. And I can count tons of times, at least in my own career, where I've done that. I've written down why I made a decision, and then some facts of the matter did change. Either something changed in the real world like, oh, you know what, the customer doesn't want that anymore. They want this other thing.

Ian Varley: some other kind of constraints have changed like, oh, you know what, disc space is cheaper than it used to be, or computers are faster than they used to be. And when we look at the decision in light of those changed constraints, we might say, it wasn't a bad decision then, but it's a bad decision now and we can change it. And so I think just that practice is hugely important. We've also had a lot of success with using an RFC process and Wes, you've spent much more time than I have on that. Maybe you could describe that a little bit.

Wesley Beary: Sure. Yeah. I think the key distinction really between decision records and RFCs at least in most cases is they contain a lot of similar things, right? They're both documents that capture what it is that you're trying to decide about maybe some of the alternatives you considered, what you talked through, how you thought about it, what decision you ultimately reached. The big difference really is a process one. So, with the decision record, it's really almost like a journal or something. I just want to capture what it is that I thought about it, and what I did in my small group or on my team so that it's there for posterity, so that we can refer back to it, so that it's clear, so it's explicit.

Wesley Beary: With an RFC, there's usually tied in some amount of seeking approval or at least sign off kind of from a broader group. So, once you've kind of gotten to the point of writing things out, you actually bring in a much bigger group and get them to provide feedback, and try to make sure that you're all kind of on the same page. So, it becomes important in places where it's really important that the decision is coordinated because there's a broader group of stakeholders. There's a larger impact, that sort of thing.

Ian Varley: Yeah. And I should've said RFC stands for request for comments. I didn't mention that.

Wesley Beary: Yeah. And of course then the process things get more complicated. And in some ways the effectiveness of the communication becomes much greater, because now there's a lot bigger group of people who are coming from different contexts that have different ideas about what is right and wrong. And you're really then getting more into the area of influence and trying to get everybody on the same page to agree, really, that among the things that you could have decided, that this is the reasonable thing to decide in the current context. I think another important part of recording decisions like that is just that it gives you the opportunity to learn how to become a better decision maker, which is also sometimes I feel like non-obvious, that like decision-making in and of itself is a skill. I think most of us just do it, and don't really think about it as something that we could grow better at.

Wesley Beary: But in many cases, I think reviewing an old decision, it's not really about whether or not that decision is right, in many cases it's, did I go about making that decision in a skillful way? Did I bring in all the right stakeholders? Were there other perspectives that I should have brought to the table as I thought about this, or other factors that I left out? Maybe I just didn't think about security that day for some reason. I was having a bad day in terms of my security stance, right? And so coming forward into a new decision, I could say, oh, right, that other time I really didn't think about security as much as I should have. I should make sure it'd be on that this time. So, little things like that can really make it, so that the next time you make a decision, even if it's a totally unrelated decision, that you will be able to do it more skillfully, which I think is also a really important thing.

Laura Fletcher: That's really interesting one. I like the idea of having like a personal gain from really strong communication in the first place. I'm curious, you've talked about that being able to reflect on the quality of your decision making as kind of after the fact. Is it always after the fact reflection or just by virtue of documenting it? Can you kind of review your decision making in the moment and is there value just to the act of writing it down?

Wesley Beary: I mean, I've certainly found value just to the act of writing it down. In a lot of cases when I've done it, I've used a template for instance. So, even just that by itself means that my process of making decisions is more consistent than it would be if I just sort of like went off on a little walk and thought about it, and maybe came to a conclusion. Doing that, you're going to probably not be nearly as consistent about what different factors you consider, what order you consider them and then maybe even like how you write it down or not, all those kinds of things. So, I think that has been helpful. In general, I have tended to find it helpful, but I've also found it difficult to sell that to other people, I guess, is kind of where I land. So, that makes me question whether or not it's broadly useful or not. I think in a lot of cases, people are like, yeah, but this seems like a lot of work.

Wesley Beary: I've just made decisions historically and it's worked out well enough. So, can't I just continue to do that? And of course the answer is, yes, you can just continue to do that, but your mileage may vary, so to speak. You'll probably have some good decisions and some bad decisions, and it may be very difficult to suss out what made them good or bad. Did you just get unlucky? Did you just get really lucky, or is there something underpinning that? And so I think if you work on it as a skill, the nice thing is that in aggregate, you should tend towards better and better decisions over time. And so, yeah, you'll still have some bad decisions every once in a while, but there should be fewer of them and they shouldn't be as bad and you'll have more good decisions and decisions that trend towards even better than your decisions have been in the past. You're still going to have good times and bad times, but overall, the average level should increase if you're making that investment.

Ian Varley: Yeah. And I think that generalizes actually. When we think about the importance of explaining a decision and how that influences your thought while you're making it, I personally find that to be true about every aspect of thinking. And maybe that's just me because I write a lot. But for me, writing is a way of thinking. Writing is a way of getting my thoughts crystallized to a degree of, I guess, formality or explicitness that they don't have to be when they're just in my head. So, there's this really famous paper from, I think it was from the 1980s by Peter Naur, who is a computer scientist. And the paper was called Programming as Theory Building. So, the context at the time was, a lot of people back in the seventies and eighties, sort of viewed programming as essentially typing. If you were writing a program, it was like, well, you know what you need to do. just type in the program.

Ian Varley: And what he said in this paper, and he made a very good case for it was, "No, the essential activity of programming is actually building a representation." He called it your theory. Building a theory of correspondence between some problem in the real world you're trying to solve, and the solution over here in the program, right? And the richness of that theory and the correctness of that theory is what's at stake in software engineering. It's certainly possible to build lots of complicated engineering artifacts without writing any prose at all. But if you don't do that, you're missing a huge opportunity to capture and crystallize those theories that are in your head at that time. And you know what, it's not just for other people who might be reading it, it's for you because you're not going to necessarily remember your mental state, this very complicated mental state that you had while you're creating some complex engineering artifact. So, I think this act of communicating and writing is just such an essential part of the process of engineering in the first place.

Wesley Beary: Yeah. I mean, I think it reminds me of the notion of the cognitive bias. It's called the illusion of explanatory depth, actually, which I feel like in some way is like that is programming large, is the way it feels sometimes, where the notion is like, if you ask somebody how well they understand something, they will often give you a relatively confident answer. But then if you ask them to explain in depth that thing, things kind of go off the rails. So, the classic example is probably, there are two, really. One is a toilet, right? How well do you understand the way that a toilet actually works? Most people will say, I don't know, like seven out of 10. And you're like, okay. I ordered numbered list of the steps that happen as you flush the toilet. And they'll get to one, like press the handle down, right?

Wesley Beary: And two, oh no, maybe I don't actually know how this works at all. There's more going on to this than I realized. Yeah. And I feel like programming comes into a very similar space where we think we know what's going on and we just weighed in and tried to make the best of it, but we actually get to step one, step two, and then kind of say, oh no, oh no, maybe I didn't really understand what it was that I was trying to solve for here or how I was going to do it. And so, yeah, I think, you know what Ian's saying here of taking the time to actually write it out, gets you out of that, right? You get to the point of realizing how much you really do or don't know.

Ian Varley: Yeah. There's so many factors that make writing absolutely critical as a part of what you're doing from an engineering perspective, and yet many of us are so terrible at it, right? And it turns out that writing and communicating well is actually quite a bit harder than it seems. Laura, maybe, could you take us through some of the kind of basic ideas around how to communicate well, so that we're not just flailing out here?

Laura Fletcher: Yeah. I mentioned at the very start, this idea of driving a particular behavior. And Wes echoed that talking about two of the major reasons why we write are to educate or to persuade. And so when it comes to if we're all aligned on, we're trying to drive a particular behavior or prevent a particular behavior, then there are some research based techniques that work particularly well. One of the things that we have talked about and I think we have some varying opinions, so I'll be interested to hear what you guys think. We've talked about context and how providing a certain level of context is really critical for explaining a concept. In learning and development, context is recognized as really critical for making the jump between the classroom learning or reading, or however you obtain the knowledge, and then transferring that into however you're actually going to use it, the context in which you're going to use it.

Laura Fletcher: And so while something can make perfect sense when you read it on paper, kind of like the toilet flushing example. Makes perfect sense when I read it, it doesn't mean that I'm ready to get in there and make the repair if I notice that it's not happening correctly. So, giving that context of, okay, when I get into that situation, give me the specifics of what I'm going to see or what you saw when you were in that situation. Things like that, that are really helpful. I wonder if you guys have strong opinions about the level of context, because of course you can take that to an extreme.

Ian Varley: Yeah. It's really actually quite difficult to get right. Because I was going to say, most of the time people don't give enough context. And I think it's useful to distinguish between context and details. Because one thing that I see really often with engineers when they're trying to write something, is they will go into such excruciating detail, that it's impossible if you're not actually working on the system side by side with them, to even follow what they're saying. They'll paste in reams of code and stack traces and all kinds of other stuff into this explanation, and that can make sense if you're the one working on a particular problem. But for an outsider, it's just way, way too much detail, right? All you needed to know was this function does X.

Ian Varley: And yet here you have 16 examples of it doing X, right? Now, on the flip side, what I think people don't give enough of is the kind of context that you're talking about. Why does this thing exist? Who built it? How long has it been here? What kinds of problems have we seen with it in the past? What's the basic situation here? All of this stuff that you're basically blind to because of something called the curse of knowledge, which is, it's very difficult for you to remember that somebody else doesn't know a thing that you know. And so you skip all the stuff they really need and then give them all this stuff they really don't need. And that's sort of classic bad context in my experience.

Wesley Beary: I think there's a real paradox in that. I think in many cases people do lean into the more and more detailed side of things as you described. And in many cases, the more detail that you get into in that way, the more context you would actually need to provide in order for the person to understand what's happening, right? So, it goes like in the exact opposite direction of what you would want. So, really, when we say context, what we mean as I think both of you alluded to is this notion of like, why does this matter to me? What's in it for me? Why should I care, right? That's really what you want to make sure that you get to the heart of, it's not about going deeper and deeper into the nitty gritty of what it is that you're trying to talk about.

Wesley Beary: Sometimes you might need to do that as well, but the more than you need to do that, the more you probably also need to understand why that nitty gritty is also important to the person that might be reading it and understand how it relates to them. Which can be really hard, because one of the other things we've sometimes talked about is this notion that what matters to you person A, and what matters to person B might be quite distinct. And so now you're in this place of, is there some way that I can structure and frame this document that will matter to both of them? Or maybe am I even getting into the space that I need to write two separate documents or two separate sections in this document where each section addresses one set of concerns? Because sometimes it can be really hard to squish all of those different concerns, and where they're coming from and everything else into one thing and really have it remain coherent and sensible.

Laura Fletcher: I really like the distinction between details and context, kind of separating those two. And it reminds me of another communication best practice that we've talked about, which is this avoidance of jargon and complex language. When you talk about having 16 examples of how X does Y, and in the instructional world we talk about cognitive overload. It's like you're already explaining something that is a complex idea. And then on top of that, you're forcing me to process complex language and lots of technical terminology that even if I know it, the additional cognitive lift, it makes it more difficult. And so we talk about a concept called scaffolding, which is building on a most basic foundation. You're starting with the common denominator of like, okay, here's what we all know, and this is why you see analogies be really, really helpful, not just for the storytelling component, but an analogy builds on a concept that you already know.

Laura Fletcher: So, if you liken the toilet flushing to how a dam works, this idea of building on the most basic. And so in order to do that, you're thinking about every word that you're writing. And that seems like such a tall order, but the fact is a normal adult reads at a ninth grade reading level. That's the level where you're not having to look up lots of words, every other sentence and everything, you're processing things fairly fluently. So, they read at that level, but their preferred reading level is actually about two levels under that. That's where it's just really comfortable. And so you'll see popular novels being written at the seventh grade reading level for that reason. And so just like with any complex topic, if we can strip out any additional brain lifting that we're asking our reader to do, it ensures more and more that they're going to comprehend, that they're going to remember what it is we were trying to get across in the first place.

Ian Varley: I think that's so true and makes me so sad. But for me. the important part of this is this idea of streamlining, of really thinking about what is the mental load of my reader going to be as they're reading this? And Steven Pinker actually talks about this in his book, The Sense of Style, where he says, actually, as you're reading a sentence, you're having to maintain in memory, some structure that is the parsing of the sentence and the sense of the sentence. And there are ways you can construct a sentence where you keep that memory load low as they're going, right? So, they don't have to stack up a whole bunch of stuff before they get to the payoff. Or you can structure a sentence the opposite way where you have comma after comma, all of these clauses, but you're not really saying the thing they need to know until the very end.

Ian Varley: And so they have 50 words stacked up in memory, trying to hold that all in their head before they understand what you're even trying to say. So, there are ways you can construct language, but the important part there is not so much how you do it, is that you do it. In other words, that you are actually paying attention to what is going to be the experience of the reader here, right? And that can be really hard to do when you're looking at a piece of prose, because you're so used to it. You've already read this paragraph 12 times, you know what it's saying, you know what you're trying to get across. It's very clear. So, one trick that I sometimes use in that respect is, there's a reason people say, oh, you should have multiple drafts and multiple revisions.

Ian Varley: At least for me, the reason is freshness. The reason is so that I can come back to that piece of writing with fresh eyes the next day and go, oh, that kind of made sense to me yesterday, but it's so laborious the way that I say it. I could say that so much more simply with X, right? And then you're doing all of that kind of work. And in the process, you'll notice. You'll notice those cases where you used a word like utilize, right? You have to utilize such-and-such, and utilize is essentially a pointless word because it is 100% substitutable with use, right? So, you'll notice those things where you've done that and you'll fix it.

Laura Fletcher: I don't know if it's a misperception or, I don't know how to label it. But especially in academia, I see a completely different language pattern. My perception is that it's used to drive credibility. That we're writing like this to show you that we know this topic. And when we're trying to explain, educate, persuade, I don't think that kind of use of complicated language does us any favors. You're right, Ian, sometimes the right word is the right word, and it happens to be three syllables or more. But I think a lot of times that's not the case and there's easily substituted word that levels the playing field across your audience. Because not everybody, like you said, curse of knowledge, not everybody knows exactly the same things that you know.

Wesley Beary: That kind of drives me nuts a little sometimes with academic writing actually, that you get this notion that if you were to consider what the goal of the writing was, it seems like the goal of the writing was to demonstrate intelligence or something, not really to make a point or communicate something to someone else, right? It's sort of grandstanding or something or to sort of like, look at me how great and smart am I. But at the same time I'm not sure that I can blame them that much because that's the example that they see in other academic writing, and so there's a certain amount of like trying to match that context. Still drives me nuts though.

Ian Varley: Well, and in Sense of Style Pinker actually has another way of describing academic writing, and it's that it's just bad. It's just bad writing. Another thing that I find missing in academic writing and a lot of technical writing, and this is something that you really opened my eyes to, Wes, is the absence of any kind of what you might call storytelling, right? Any sort of narrative arc, any sort of concrete details. Talk a little bit about that, Wes. What's the point of using story as a part of your communication?

Wesley Beary: I think there's a couple of key aspects. One relates back to the notion that Laura was talking about of scaffolding, right? So, in a lot of cases that can provide some common foundation for the conversation where everybody's kind of on the same page, right? You don't have to know this particular jargon or whatever. You don't have to have necessarily been in the room at the right time to have seen this thing unfold, that would give you the context that you need. You tell the stories that everyone is brought to the same page. Stories are just something that we grow up with, right? From storybooks as kids up through movies, TV, whatever that we consume now. It's just a very familiar form of interacting with the communications and receiving messages that helps to sort of bring us along and give us more of an opportunity to see ourselves in the communication, which I think that doesn't necessarily happen if it's like very strictly technical and detail oriented.

Wesley Beary: You don't see yourself in that. You're just like, oh, this is information that is being pressed upon me. I don't see myself as a part of this. That is the power of stories in many ways, right? That we can see ourselves in that story in some way, shape or form. And so they tend to when used well, at least be much more memorable and really help to drive things home. And if you, for instance, go and watch two presentations, and one has like no element at all, it's very detail oriented. And another one has a narrative element. If you asked people who watched those presentations like even an hour later, people would probably be able to tell you about that narrative one. And the number of people that are going to be able to tell you about the detail oriented one is going to be pretty hit or miss. A week later, probably nobody's going to remember the detail oriented one at all.

Laura Fletcher: I think that memory piece, for me, that is the big selling point. And this was news to me that there are actually like giant memory competitions. People who compete to see how many random things they can remember in a row. And so I listened to somebody talk about how they do this, and they literally are creating a landscape in their mind. So, like a place they're familiar with, and associating the random things they're supposed to remember within that physical space. And so to me, that is what we're doing when we're telling a story. We're giving people, I think of it as a Christmas tree.

Laura Fletcher: We provide the Christmas tree and then we're hanging these ornaments on it so that they can have that spatial relationship to have in their mind. There's an oft cited statistic about stories making things up to 22 times easier to remember, which sounds very dramatic. But then you see it in practice and it's like, oh yes, well, I did remember the color of the car. And I did remember the perpetrator's height or the shade of the sunset on the beach. So, when you see it in action, it's pretty eyeopening how valuable storytelling is for retention.

Ian Varley: And it can be tricky in a technical setting to actually do that. I need to tell you about a new database partitioning technique that we are pioneering. And let me tell you a story about some rabbits that had two sons, I don't know. Sometimes it can be a real reach. So, for me, I actually kind of embrace that absurdity sometimes a little bit because I think that ties into another aspect of good communication that I really lean into heavily, which is humor. What's the value of some level of humor or levity in our writing?

Laura Fletcher: Well, I think humor is something that sets something apart from just a landscape of facts. So, principle of different teamwork sets things apart in a way that makes me remember it. So, Ian, in your presentations, you incorporate a lot of surprising gifts and images as you kind of weave your story of your concept. And I can still remember some of those from presentations of yours that I've seen. So, because they're unexpected, they stand out and those are things that we remember. And you can use this for good and for evil, right? So, if you're highlighting things that don't matter, if you're using principle of difference to highlight ideas that really aren't supposed to stick with people, you're taking up memory space in your reader's mind. But if you can use it really strategically like I think that you do, it really helps to cement certain topics.

Ian Varley: And the other piece that I think fits in there for me, is there's a kind of signaling that happens when you add a little bit of interest or humor or something unexpected in a piece of writing. The other thing that it does is it telegraphs to the reader, Hey, I cared about this, you should care about it too. I cared enough to put a little extra into this. I'm not just doing the rote thing that I have to do. And so you might actually want to pay attention to this because you might find other things that are interesting to you. It's like a signal between two human brains of like, Hey, open your eyes. This is real. I'm here, I'm talking to you. And so I think that personalness and that personality I think it's a thing that really can help and can give that extra push to make the thing that you're writing or communicating really get across.

Laura Fletcher: So, there's one more concept and I think we would be remiss not to discuss as part of thinking about what makes communication really effective. And that is repetition. And I think this is delicate to some extent, because it has the evil brother of redundancy. Especially as we think about the importance of concision, redundancy is something that should be stripped out every time. But repetition is essential for getting people to remember something. That's the only way that we form memories is by hearing something more than once and having to like consciously think about a concept. Otherwise your brain deletes it when you go to sleep, that's making more space. And so within a document or within some kind of communication message, when you talk about a presentation and you say, you're going to tell them what you're going to tell them, you're going to tell them about it, and then you're going to tell them what you told them.

Laura Fletcher: I think that's an easy way to incorporate repetition to really drive home what your main point was. To your point, Ian, having non fresh eyes, I think it's easy to think this is crystal clear and somebody reads your paper, and take away the completely wrong message from that. Internally there've been some really good examples of recent initiatives, especially around creating team agreements. I feel like we've been seeing information about team agreements in lots of different channels, and that repetition starts to make you think this isn't the passing fad. I understand what they are. I understand I'm supposed to work on those with my team. I thought that was a great example of using repetition across channels really, really well.

Wesley Beary: You and I come at this a little bit differently. I know when we work on documents together, especially this becomes apparent where Ian leans much more strongly on repetition than I do. And I think I try to be concise to a fault, to be honest. So, I know that that is my predilection. Beyond that, I think in many cases, my preference maybe actually is to think about more what Laura was talking about, right? This notion of repetition across channels and across messages, rather than within a message. I think there's a lot of value to spacing out the repetition basically. Yes, I do want to repeat myself. I want to make sure that that message is clear. But if I say this 10 times in one document, I'm not sure that it's going to be that much better than saying it eight times or maybe five times, or maybe only three times.

Wesley Beary: Because within the context of that document, there's only so many times that it's going to stick out. That it'll be different enough, or surprising enough, or interesting enough for people to think about it more, versus if I repeated across 10 different channels, 10 different documents, I feel like that lands probably much stronger. But it just depends because there's some things where you just don't have that opportunity. You're not going to have 10 opportunities to communicate about this thing. You're going to have one opportunity to do it. So, of course, as in all things, there's some balance that you have to seek out here.

Ian Varley: For me, the idea here of repetition, like there's another subtle related idea here, which is redundancy for error correction. If you think about information transmission, there's a sort of fundamental principle of information transmission that you can reduce errors in transmission by adding redundancy. So, in writing and in communicating ideas, for me, the way that this manifests is trying to say, okay, well, here's the sentence that perfectly encapsulates my point and what I'm trying to say. Then assuming like, okay, now what if somebody just didn't get that? What if for whatever reason it didn't land for them, what would I add to this?

Ian Varley: Maybe a paragraph later that says something like, so in other words, that didn't say it a different way, right? Because if you're just repeating the same thing, it's not necessarily going to make a difference. We're not talking about information transmission over lossy wires here, we're talking about something not landing in somebody's brain for whatever reason. Now, we're talking about all this as if writing here is this thing that you just sit down and you do. And as long as you understand the stuff we're talking about, you're going to do it well. And that just could not be further from the truth, could it?

Laura Fletcher: Reminds me of the old joke. How do I get to Carnegie Hall? And the guy says, practice, practice, practice. Kind of same idea.

Ian Varley: Yes. Yes. Certainly in the way that I've experienced writing over my career, it's not like some particular thing transpired to make me into a great writer, it was practice. It was that I write all the time. And I think it is a bit like playing the violin in that, being told what to do can only get you so far. It's just a matter of you doing it. You getting out there and doing it over and over and over again, and learning from your mistakes in a sort of deliberate practice kind of way.

Wesley Beary: I think one important follow on to that is the notion, at least for me, of how important it is to get feedback on that writing. I think all too often, especially earlier in my career in life, I would write up this wonderful thing and like hit send, hit publish, and that was that. I was done, right? And I've just learned so much from taking that thing before it goes out to the broader audience, and asking a few key people to just say, what did you get out of this when you read it? Did it make sense to you? Did the points that I was trying to make come across to you, or did you take from it what I was trying to send from it?

Wesley Beary: That is just like really, really valuable. And in the same way, I find myself now in a place where I often am asked to edit other people's documents. And I often learn a lot from what it is that they said and how they said it, how it's different, and how helping them make their writing more effective also gives me a new perspective on how I can make my own writing more effective.

Laura Fletcher: Yeah. Having a good editor is invaluable. I'd say the other thing that wasn't necessarily obvious to me, especially as I got into instructional writing, is what drastically different styles of writing exist out there. And adopting a very different voice for different purposes is useful. So, when I started to do instructional writing, I came from a job where I had been doing very formal writing. And then we got into writing instruction and this paragraph style did not work, nor did that voice of authority. And so being able to have a little bit of fluency in the voice that you use, depending on who your audience is and what your purpose is, goes a long way. And so verifying that too with a reader and editor can be really helpful to make sure you're striking that right balance for who you're trying to communicate with.

Ian Varley: Yeah. Yeah. I could not agree more. And I think you can write just for yourself to enjoy it, but most of the time writing is communication, writing is interpersonal, right? And so a lot of getting better at writing is just getting better at vibing with people and understanding them, and understanding how other human brains work and how it works to share thoughts with another human brain. And so I know we're just about out of time here, but actually, maybe that would be an interesting note to end on. Do you have any resources that people could lean on as far as getting better at writing and getting better at communication?

Laura Fletcher: One of the books that I really liked, it's extremely practical. Really almost a handbook. It's a book by an author named Patti Shank and the book's called Write and Organize for Deeper Learning. And it's all about ways to not just write language, but then format it in ways that are really easy to process and understand. So, really communicating to drive that call to action or behavior change.

Ian Varley: That's a great one. And I have not read within that, I'll put that one on my list. I know I referenced before Steven Pinker's Sense of Style, and I do highly recommend that. I have had people tell me that it's nerdier than they were ready for. And it is. It's like, he's a linguist and he's really talking about how we actually process language. But if you really want to get into it, I think it's a great one. And I'll throw one more in there, which is, there's a technical writing class that people speak very highly of. I haven't gone through it myself, but from Google, and in fact, we'll put these in the show notes, so you don't have to search for these. This class actually really takes you through all the nuts and bolts of just proper powerful English prose in a technology context. And so I think that's also just a great way to walk you through things.

Wesley Beary: Ian, I don't have a particular book or something to point to, but I think a big thing that I would point to is more about sort of like a process or practice of how you would get better. I think a really valuable thing to do is to see if you can find something that you can anchor to that's already happening on a consistent basis that some good writing might really benefit, and see if you can be the one that does that writing. So, maybe your team needs to produce a newsletter on a regular basis, or maybe you just want somebody to be able to take the really raw meeting notes that came out of an important meeting and write it up into a little report that other people can more easily digest. There's lots of opportunities that happen on a regular basis for you to take on some technical writing.

Wesley Beary: And if you don't find more regular opportunities to do it, it's going to be hard to get better. So, if you can find things that are already happening that will give you an excuse to do it, it's going to be a lot easier than just this abstract notion of like, oh yeah, I really should work on my writing. Someday something will come up and I'll work on it. Really tying it to something can be very helpful. I mean, you can also, for instance, commit to writing a weekly or a monthly blog post, right? That's another great way to say, I'm going to put my feet to the fire that this is something that I want to make sure that I actually am spending time practicing. So, this is a way to make sure that it's actually happening.

Ian Varley: That's awesome. Well, I just want to say thank you to both of you, to Laura and to Wes for this really interesting conversation. And thanks to all of you for listening and we'll share those references and some other stuff in the show notes. And we'll see you next time.

Speaker 1: Thanks for joining us for this episode of the Codeish Podcast. Codeish is produced by Salesforce, where our technology and product teams have built a platform that helps companies around the world connect with their customers. For show notes from this episode and all other episodes, visit heroku.com/podcasts/codeish. To read more about software development at Salesforce, check out our blog at engineering.salesforce.com.