Wojciech Pituła: Communication for Developers: Estimates, Code Reviews, and Other Hard Problems

This talk focuses on the importance of effective communication for software developers, highlighting the challenges faced during code reviews, estimates, and daily interactions. The speaker emphasizes that many misunderstandings arise from vague communication, particularly regarding project estimates where developers and project managers may interpret terms differently. They introduce concepts like the Shannon communication model to illustrate how messages can be encoded and decoded in human interaction and stress the necessity of understanding the audience. The talk progresses to practical tips for clear communication, such as adjusting language based on the listener's technical background, using explicit language in estimates, and creating accessible comments in code for future developers. The importance of collaboration, maintaining open communication channels, and fostering a positive work environment are also discussed, ultimately advocating for developers to be aware of their communication practices.

[Music] ladies and Gentlemen please welcome our next speaker Yi picua presenting the topic communication for developers estimates code reviews and other hard problems hi everyone uh I kind of really hoped AI would read my name that would be funny uh but it is what it is uh glad to see all of you here I hope you'll have a good nap um I skipped lunch for that particular

reason because if I ate I I would fall asleep and that would be right now and that would be a little bit awkward uh but anyway um let's begin okay I needed slides so I can block them out uh what do we do as software developers we write code we test that sometimes even design something um we have some kind of architecture we deploy that code but

throughout all those activities we talk we talk a lot we talk with our fellow developers about the code we have written maybe we talk with the QA about how we have tested that code maybe we talk about the the architecture that we have designed we product about the problems we have solved right but then I realize that we never or very rarely talk about all this talking

and think about all this talking and this is why I decided to do talk um initially I wanted to share tips tricks teach you something about effective communication but then I realized I'm squeezing something like three days Workshop into a 40 minutes talk so my goal is a bit a little bit different I just want you to be a little bit more aware of the communication you

do every day as software developer I will still short tips and tricks but the goal is just awareness so I also wanted to introduce myself um but then I realized it's not exactly relevant for the stock so what is relevant is that I read quite a lot some of those books um are were about psychology in general some about Communication in particular what is also important I

talk a lot and what's even worse I don't know when to shut up uh if you ask my manager you will learn that probably all my failures through all the last few years were related to communication I don't blow up production I just screw up um so then I thought okay maybe maybe I need to step up the game a little bit I like to think about

myself as average communicator but at the same time the Baseline is not exactly high so I'm decently developing uh the decently communicating software developer uh okay that's it uh that's it let's talk a little bit about about the communication you might be aware about of Shannon communication model it comes from information Theory it's about machine to machine communication there is a standard it produces a message message

gets encoded decoded received boring okay so how does it translate to human to human communication there is something you want to say okay you have a thought you have some kind of a message you want to pass so you put words around it and either write it down or say them but you basically communicate it then those words gets interpreted uh and the other side formulates a

thought or understanding in their head okay so the goal of communication is to make the both sides equal so what the other side thinks he wanted to set is the same that you said okay as simple that and that's enough of theory let's jump to some examples in practice estimates who has ever had to estimate anything please raise your hand perfect whole whole whole uh and who

had issues that I think the same subset of people um and and you might ask why this is a communication problem so let's think about this hypothetical scenario um PM comes and ask when this will be done okay and developer answers in around a week okay and what happened is that PM understood in a week we will have that feature running in production for our whole user

base and what developer really meant was okay if I drop everything right now and don't do any operational things and if everything goes smoothly then maybe in a week I will have a open pool request and maybe maybe tests in that pool requests okay so you can clearly see there is like the same words mean different things for different people so how uh how can we do

that that uh to do first we need to understand what is the goal of estimating things we have to provide an number value that is that has the same meaning for both sides and to do that we need to understand why the other site needs that number because there is quite a lot of reasons um to be asked for an estimate there might be a promise made

to someone be it a user or a regulator there might be a market opportunity you want to catch there might be some internal planning happening or not even planning but just prioritization you have to task you need to wait which one is bigger and then uh compare it with impact and choose one okay more often not there is no reason at all someone just thought it's a

good idea to ask for an estimate but they don't really needed um and that brings us to the very to the first very important point about communication you cannot communicate effectively without understanding the other side so this is something that will repeat over and over during this talk okay so how do we how can we communicate effectively the estimate my advice is be very very explicit and

what does it mean we start with a scope we say what are we going to estimate we let's say we estimate in developer days so we say how much work time it is so our estimate okay then we explicitly mentioned the uncertainty Factor so how many unknown things are inside that estimate this can be something from 1.1 to five okay and you multiply the dev Days by

this number you say what is your assumed developer assignment and developer availability because you might have one or five developers and your developer might spend one day a week on this task or five okay and then you repeat what will be the end result and by when it will be delivered and if you do that you expose a lot of informations that can be discussed so if

someone disagrees with your estimate they can point to the fragment they disagree with okay so maybe they disagree with their Ro estimate of Dev days but maybe they disagree with uncertainty Factor they thought that okay this is we did it 500 times there should be no uncertainty and then you can have a discussion about that um and this is an example I don't think it's very interesting

but yes 55 m dayss one to 1.2 4 days a week one develop and then you you calculate the date uh now a small deter estimate versus commitment those two things are very very different and the misunderstanding about those two words are the for me the most common source of issues you need when you estimate something you need to be very clear that this is just an

estimate it doesn't mean anything it doesn't mean I will start doing something okay it's just a number that I think it can be done in that amount of days or story points or whatever commitment is estimate in practice it means like I estimated and now I commit to doing that in that time okay uh so pay attention and this brings us to the second important Point words

matter sometimes they don't but sometimes they do as you have just seen okay we are done with estimates now we go to implementation um and to do any kind of implementation we can we have to have discussions with business and one thing that is particularly important when you discuss with the widely understood business so product or any other non-technical department um you have to adjust your language

what does it mean you don't say words like pull request comit Branch uh deployment High availability those people probably don't understand those terms okay you have to focus on what they understand and that brings us to the third point that is very important always adjust the content to the audience you can have say the same thing on a five different in five different ways depending on to

whom you're speaking okay let's go forward code comments and you may wonder why it's a communication concern it is because comments are messages into the future you write something today and someone reads it in two weeks two months two years from now uh and to communicate that effectively you have to imagine what might be needed in those two weeks two months two years from now so we

have to imagine what the person reading your comments might need from you and this is why we often say that comment should focus on why and not what okay because what is in the comment they see in the code they see it but what they don't see is why you have written what you have written and a side comment to that I strongly believe humor is valuable

who everyone who saw had found a joke in a comment especially during the long day of debugging knows what I'm talking about it's just a good practice to put a little bit of humor into the code error messages another message into the future you write it today someone will see it it's special circumstances at some time in the future and now you have to imagine what they

might need so you can say that operation is unsupported this is a true statement but it's doesn't give you anything or you can say that can't update address of an inactive user this provides much more information makes it much more actionable for the audience of your message okay bre bread crumps um sooner than later you will need to do a little bit of code archaeology you have

to figure out why something was done as it was done and then it is important to help that person who's doing the investigation right now and the way to do it is to leave breadcrumbs behind you okay what are breadcrumbs links links to GitHub issues stack overlow uh questions J tickets GitHub comits branches slack conversations everything you can think of that is relevant to the things you're

doing try to link it together because the person doing the archaeology will thank you a lot okay another um important topic a little bit controversial built in the in the open um when you do something you never know who might be interested in what you're doing who might be affected by it and you don't know if you're not missing something maybe uh maybe someone did exactly the

same thing just yesterday or maybe you're trying to do something that 10 people before learn uh like figure out it cannot be done or maybe uh maybe you're D doing something that you shouldn't be doing okay and if you don't communicate enough about what you're doing you will not learn that uh so yes the the simple answer is just use slack channels and meeting notes instead of

direct messages and that's probably good enough but we'll talk about this a little bit later because it's more complicated keep people in the loop uh our job as software developers is to write maintainable software if you fall under the bus the software can no longer be maintained if you didn't share your knowledge your job is to not be Irreplaceable okay so that's simple as that so communicate

a lot and share a lot of what you're doing coordinating releases um you might confuse release and deployment especially in smaller organization this is the same thing you deploy something the feature gets released in more complicated environment it's uh something else entirely because you want to deplay often uh but you want to release in a coordinated fashion because it might the given feature might affect multiple departments

especially nontechnical ones like uh compliance legal operations um yeah support anything and then the releases needs to be coordinated and if you're lucky there is someone else doing that it can be a product manager project manager program manager uh release manager there there's managers um but if not it might be the developer who build it okay uh and then a little bit of advice here just put

a slack thread a bunch of emojis and bullet points and that's it just update them as people report that they like hand report handshakes and yeah you're done great we've implemented our great feature now we open a poll request our goal is to get our code reviewed and accepted and how do we make that happen the first thing we need to do is to find the reviewers

okay and the important Point here is that you need as many reviewers uh but not more uh because if you ask too many people for review especially your uh for example your whole team something called diffusion of responsibility steps in and everyone thinks someone else will do it and no one does it and then you wait two weeks for your review okay so Target very specific people

and um like if you need one approval maybe ask two people okay if you need two approvals ask fre people and stuff like that um another advice put a deadline like communicate to your reviewers by what time you want this to be reviewed okay so something like this is a PR I would like to have uh I would like to merge it by Friday okay it's just

your intent but then they can adjust their planning like fit it in before Friday or they can tell you I will not have have time find someone else and that's perfectly fine just but without that information this is not possible to happen okay here is the example not really important but one of those two messages has significantly higher chance of getting a fast review um another thing

if you want your PR to be reviewed you have to make it reviewer friendly what does it what does it mean usually it means it has to be small unfortunately I'm completely incapable of doing small PRS uh and so if you're like me let's look for another ways to make it reviewer friendly if the change is Big um okay so the first thing is description right what

the pr is about just be brief if you're write a wall of text no one will read it you you haven't helped anyone highlight the most important pieces like if you modified 100 files but the important change is in two of them put comments yourself on the pr on those files saying why those changes are important so the reviewers can easily them uh clarify what is the

state of PR okay so you can mark it as draft but maybe it's not draft but you still need to manually test it right so write in the description that Tod do that you're still intending to do with that PR so the reviewers can act accordingly okay now a bit controversial topic I don't want to start a holy war but um if you like a clean git

log then rebase uh um before or after creating the PR but when the pr is open and being review you're shouldn't do any Force pushes why because that's what reviewers see the same commit message repeated over and over and they have completely no clue what happened okay so no Force pushes in general no amendments nothing because you're messing up for your reviewers okay speaking of the review

viers now we're the one uh our goal is to give a good review and not only that we also don't want don't want to make more enemy enemies that we already uh have uh and that's pretty hard okay so the first advice level of give a not all comments are made equal some of them are more important than others uh and you can say that explicitly unfortunately

there is no standard at least I haven't seen one uh but you can figure it out having said that there is thing that has standards and that's conventional comments uh you can check the page for details but basically those are just prefixes with clearly defined semantics that you put on the comments uh to communicate your intent is it a question does it have to be done how

be is it a need peek or or stuff like that you have a good resource to help you okay now probably the hardest point of this presentation Don't Be a Jerk okay that's hard I know um we're always sometimes a bit of a jerky uh but how do how do we not be first thing propose Solutions if you spot a problem for example you don't like the

name of some variable don't say it's a bad name try to provide Alternatives if you cannot think of an alternative write it down like okay this name is bad but I can't think of a better one maybe someone else has an idea okay just say that you thought it the second thing offer help if you see that someone is struggling with the pr they apply fix after

fix and no fix is uh good enough then stop commenting Reach Out offer per programming or some other way of helping them like be be a good person show empathy okay so you see that someone create a PR and is applying fixes for the last two weeks okay and all the comments are valid and the fixes okay um but then for some reason the process doesn't end

okay uh so you need to understand that no one wants to have a pool request open for two weeks they want to have their task done okay and showing empathy is just about understanding that and trying to help them get their goal merging that PR okay maybe it will never be merged because uh it's too hard or something but like yeah they feel bad you need to

that and related uh comment pick your battles as I said not all comments are equal not all issues are uh of the same importance so sometimes it's important to let people fail okay people make mistakes they learn on those mistakes and uh if you're a senior engineer that and you do a lot of pull requests and you find a lot of issues you need to understand when

is time to when is time to acknowledge that issue and go with it like let the pull request outter do that and see that it will backfire okay it's your job to prepare the system to write the system in a way that this will not compromise your business okay so they can make a mistake but you know that mitigation uh processes and means are in place so

you allow person to do stupid okay done with poll requests now let's talk a little bit about General topic of everyday hello uh yeah that was a little bit right okay don't do that that's exactly what you're doing when uh you write a single hello on slack or any other uh communicator and wait for a response just don't write what you want okay if you need more

justification go to that page and and read but just don't repeat repeat repeat something you need to understand is that people will misunderstand you misremember don't read your messages misinterpret them forget and all of those is normal this will happen and the simplest mean to fight with it is repeat what you have said some time before don't get frustrated just repeat in different words um the only

thing you can do is to think okay can I repeat it in a way that will minimize the chance of the other person Mis remembering or like misinterpreting that like so try to look for a ways to improve your message but don't be frustrated that you have to repeat things over and over that is normal how to get a response you ask a question and you need

to get a response that's something we already talked about uh when we talked about poll requests so let's dive a little bit into that you have to Target your messages because of the fusion of responsibility we already um uh if you don't know who might have answered to your question ping someone okay you might they might don't know but they might know who knows okay so if

you really need an answer ping someone because otherwise you might just be broadcasting into the void explain why you need a given piece of information or a given task done uh there's an interesting psychological study called CX study done by The Ellen langner uh where she proved that giving justification uh for skipping a line in front of a copy machine increases your chances significantly and what is

important is any justification it doesn't have to make any sense like uh the she did something like excuse me can I skip the line because I have to copy document it's obvious like we're in front of copy machine but still it was like significant numbers I don't remember but like from 40 to 70 or perent like success rate like really significant so just explain why you need

stuff uh and then explain when you need it we talked about it um uh with the pull request say when when you want by what time you need that piece of information that task uh so people can act accordingly and here is example you can say hey where can I find CPU usage metrics right send it on the channel and hope for the best or you can

say hey I need to get CPU usage of our servers not sure who can help me with this but maybe Thiago we are releasing a CPU heavy feature on Wednesday and I need to prepare the setup okay I can guarantee one of those two messages will have higher success rate uh now the important Point give the responses you want to get what does it mean if you

don't if you see a question and you don't know the answer but you know who might have it be proactive ping them okay help be helpful if you you are asked to do something and you don't have time say this okay don't ignore the message just say I don't sorry I don't have time and this should be fine the person asking just need to adjust maybe they

will find someone else maybe they will uh change plans just they need to know if you have time but not exactly now maybe like tomorrow or in the afternoon or something then also say this okay so they know you have seen you've put it to your backlog you you will look into um if you started looking at the problem and then you realized okay I will not

have the answer in like next minute or two also write this down so the person knows that you're looking no one else will try to answer the same thing and uh yeah the the person asking just get some kind of a response adjust the tones I know it's uncomfortable especially in Eastern Europe but human like people as a species evolved to prefer Smiles so we have to

smile and that's sometimes awkward or unnatural or yeah but it will make your life easier like we have to smile if you have to force yourself to smile do it is just how human brains work uh what you shouldn't do is to be overly enthusiastic uh because that can be uh very very bad uh if everything is awesome then nothing is and you have no space to

actually Express that something awesome um yeah adjust the tone the other way and that's the slide that I spent uh I a lot of time on and I like I wasn't sure if I should put it here because yes some messages needs to be harsh but it's very very tricky to figure out which of the which of them okay it's probably better to not do it than

to write down a harsh message that shouldn't be one okay so try never like use this negative harsh words or like be be grumpy but be aware that okay in some specific circumstances that is allowed it's not like you have to always be super positive formatting that's something special for the asynchronous communication um if you write something it has to be easy to scan okay people are

busy and typically will not read what you write it doesn't matter if it's a slack message or a documentation or email doesn't matter people are busy they will they might not read your message so how to increase the chances of it being R it has to be easy to scan what does it mean to be easy to scan put tldd on the top it applies everywhere blog

articles slack messages uh documentation just Express what this piece of content is about in one sentence so the reader can understand if they should read it or not bold then the essence if there are important phrases in the content the things that okay if the reader doesn't read anything else they should at least look at those few words to get their attention and maybe trigger a uh

a full scan okay so balen those phrases that use bullet points okay so if you have a lot of things to communicate don't ex don't write a wall of text write bullet points then the person can scan each bullet point like the beginning of it and see if it's relevant and then don't overdo it because if you do then your message start starts to looks like a

clown and it uh calls meetings we love them okay and B me meetings are costly inconvenient annoying and effective that's a s truth okay so yes most of us don't like meetings but there are many many cases where you can communicate more effectively synchronously than asynchronously and you need to understand when is the time for which yeah understanding think that can be pretty tricky be gentle with

pinks I told you a lot of time to Target your messages right so you have to mention someone to get a response and now it's a counterweight to that be gentle with pinks because you cause a notification on the other side and of course it's on the receiver to manage their notifications if they need Focus they should put a focus mode on and don't and ignore notifications

okay just be aware that your actions have consequences for side and that's pretty much it we can now talk of more General things that can contribute to a scenarios and the first principle of effective communication is understanding you cannot communicate effectively if you don't understand the other side okay this means you need to know what product understands what words they use you need to understand legal like

if you talk with lawyers you need to understand how they think if you talk with compliance think you need to understand your audience and then um if you understand your audience you need to understand uh the message and some sometimes you can take like let's say you're asked when this okay and maybe there is a there is something more to it maybe someone wants to is annoyed

of how long it's taking okay but maybe they are just interested they have completely no feelings about it okay so you need to know when to how to understand each message from the other side you need to ensure that the message was understood you're not uh UDP you cannot broadcast messages and hope for the best okay human to human communication as effective one is TCP like you

need to get confirmation that your message was received and understood and ensuring that is pretty hard um adjusting content to the audience so you understand how the audience feels you uh thinks feels then you change the wording you change the message for that particular audience Don't Be a Jerk okay yeah just remember okay sadly formalities conventions Smiles matter and uh sometimes we just have to force ourselves

to follow them even if we don't have time or energy um yes language if you use simple but correct the the risk you face is that it will not be precise enough okay and that can be fixed with more words if you use too sophisticated language and words that are not likely to be understood then you risk not being entirely and someone the other person might not

have the courage to ask you to rephrase or say I don't understand and they will just assume something that is wrong and then do something and then your prod blows up um so yes use Simple language unless you know the other side is native English speaker close to being one and then you can use a more sophisticated words brevity matters uh something I before the longer the

message the less likely it will be read in full okay so if you want your messages to be read if you want your documentation to be read just make it short okay and easy to scan um and it matters a lot in code commands and documentation which are basically the same thing my personal take is no one one reads documentation we had a good talk I think

yesterday about how to write good documentation um if you haven't seen I strongly encourage to watch the video but like yes maybe you can write a good documentation but even if you do some people will still not read it and just try to uh go without it and the shorter the documentation is the bigger the chance that someone will actually pay effort uh communicate in the open

another thing we already mentioned a bit um and yes it's easier to ignore the message than to play uh play a telepath I would say infinitely easier unless there was some serious breakthrough uh front um and this means use channels write meeting notes don't communicate in indirect messages um and that's it that is not um it creates noise it requires a proper setup um like channels that

will have a clearly defined goals and focused conversations uh and even if you have all that set set up people still have tendency to communicate in private that's just human nature and that's fine you just need to make it as easy as possible and as normal as possible to uh to communicate in the open one of the last things all the things I have told you all

the tricks tips um practices cost effort effort is time time is money okay so we need to understand when you need to be more effective and when you can skip all that fluff and just be very very direct to the point and with minimal amount of uh words let's say um and the final thing if you think that you know something about the communication like you learn

the practices you communicate well um then read that book and you will learn that you know nothing be probably because communication is a very culture specific things people from the US communicate differently than people from Western Europe than those different than people from Eastern Europe and then those different than uh people from Asia uh so there are very significant differences that you might need to understand if

you work in Multicultural environment okay I prepared you a list of resources so the the books are other stuff that you might want to read if you uh if you want you don't have to take pictures because you will have links to the link to the slides on the next one um here it is so we are at the end please uh remember that communication is everywhere

uh my name was roek P thanks lot if we have time for questions I'm happy to yes we do have uh too much time but for maybe one or two questions definitely uh and the rest of the questions I hope you will be able to answer at uh ask me anything Corner yeah definitely so okay let's go with the most popular one uh what can be done

when uh Reviewer is not giving approval BC of a typo in a commit message he doesn't see importance of delivering the FTR over a typo um okay that's a that's a good question um I would say take it easy and just fix the typo uh like pick your bottles I hope it's not that hard okay uh if you if I get address the spirit of the question

more like if there is something small like have an honest conversation like explain to the reviewer that you want to have it done okay try to understand why they focus so much on that small thing maybe what you think is a small thing is really not a small you're not seeing something so just try to understand when from where the other side is coming from that's my

answer anonymos have a question what would you do if a colleague does not want to adapt the pr review habits I assume you tried once twice three times and uh give feedback and this doesn't work then uh I think the the only thing you can really do is to escalate to your manager hopefully they can have uh they can help you understand what might be wrong because

not necessarily issue is on their side but uh they can also have conversation with the other party and explain to them like this is why I particularly like the individual contributor versus manager split is like manager is supposed to be good at this kind of things okay uh so if you exhausted all your means try to get help don't complain don't say this person is wrong they

are stopping my PRS do something with it no just try to get help from your maner manager explain what what you what's your problem is and then uh think together of what you can do