Press "Enter" to skip to content

Politeness or clarity?

good Monday morning today I would like
to talk about communication and how I
think there is a subtle but widespread
misconception in the developer community
that you can somehow improve the clarity
of your communication by removing
civility from it I think that this is
just a complete misconception and in
fact I’m going to make a case today that
the opposite is is true that adding
civility to your communication improves
clarity I am your host MP J’s and you
are watching pocket punch punch
a couple of weeks ago Stack Overflow
posted an article titled Stack Overflow
isn’t very welcoming it’s time for that
to change it talks about how too many
people experience Stack Overflow as a
hostile or elitist place and this was
news to absolutely no one that has
visited Stack Overflow ever and had a
soul first of all I think it’s amazing
that Stack Overflow is actually putting
like recognizing this and putting some
effort into this this is a great step I
tweeted this article and I one of the
replies was from someone that said that
they would rather have hostile and
useful than friendly and a ghost town
and this commentary went on to say that
if they can marry useful and nice then
more power to them but they come and do
things that they are going to have a
hard time I don’t want to point fingers
at this person because I think that this
is actually pretty common viewpoint in
the developer community I very often run
across this notion and the developer
community this this belief that you can
somehow improve the clarity or honesty
of your messaging by removing civility
from it it feels like these people have
the idea that niceness and politeness
and civility that’s there’s a kind of
gift wrapping paper with a bowtie that
you put around your message in order to
sneak it past their recipients and it’s
all just unnecessary fluff but we could
communicate more effectively if we just
did away with this pretty dress up of
our communication if someone is wrong
yes tell them that they’re wrong just
don’t dip it in sugar and stuff oh my
god it’s war
it’s never warm in Sweden but no it’s
one and to me this is just such an
oversimplified view of what
communication is like it’s very tempting
to want messaging a narrative to be
independent of the recipient what I mean
by that is that you want like you have
this wish that you could just craft the
objectively clearest possible message
and then anyone could parse and
interpret it that you can write the
perfect technical documentation for
something and then everyone can
understand it but in the real world
they’re just there just isn’t such a
thing as an audience neutral message
it’s just not possible to write a piece
of technical documentation that can
effectively be understood by developers
at all levels if you’re writing the
documentation for the machine learning
library tensorflow
you can write that documentation in a
way that makes it really easy for people
that are familiar with machine learning
concepts to pick it up and that might be
a good way of writing it a lot of people
that pick up tensorflow are familiar
with machine learning concepts already
but on the other hand there’s a lot of
people just playing around and getting
into machine learning right now and
probably the first thing that you’re one
of the first things at least that
they’re going to run into is tensorflow
and then they run into this huge brick
wall because the documentation assumes
that you know a lot about machine
learning the tensorflow people code then
of course like move down and make the
documentation more basic and in explain
like the machine learning concepts that
they are talking about as they go but
that would
a ton of noise to the to the
documentation for the people that do
know the machine learning concepts also
you need to be mindful of tone for
instance like if you if you’re writing
about some JavaScript concept to
experience JavaScript developers then
they are very confident they just that
pretty much they’re going for the info
pretty quickly they are thick they’re
thick-skinned but if if the person is
new they’re maybe not familiar with NPM
maybe they really like they might be new
developers to develop it in general and
they are feeling quite their confidence
is not that high so you need to build up
a little bit of lovey dovey coupling
into your messaging like okay this is
confusing but you’re going to do fine
it’s okay everyone is confused at this
point maybe you need to say that
something that you wouldn’t need to say
to an experienced developer or you might
need the developer might be hostile you
know if it’s a Java developer c-sharp
developer that is just grudgingly
learning JavaScript then they are you
know that at some points they’re going
to just be annoyed at like oh my god why
is there a yarn and an NPM like stuff
like that or why isn’t there one
cohesive way of doing doing classes what
is this prototype thing like stuff like
that and at that point you need to if
you have that kind of audience you need
to like think about okay we need to at
least address the concerns of this
person like so that they can just move
on what I’m trying to get at here is
that this thing that people that aren’t
well okay this is gonna sound
condescending but that aren’t well
versed in communication view as you know
being being nice or like
fluff is actually being mindful of who
your recipient yes like the recipient of
your message of your communication
because communication at its core is to
get stuff out of your head and transfer
it into the head of another person the
problem is that there is no standardized
API for messages between humans as the
sender of communication I
I cannot craft a message that like is
here and can then be read by and enough
and understood by all kinds of different
people that’s that’s not how
communication and messaging narrative
and and writing and teaching works what
I can do as a communicator is to
identify and understand and target a
specific target market like a group of
people or maybe the group is is just one
maybe I’m talking to my colleague so in
order for my communication to be
effective I need to spend some time
talking to my target market finding out
what it is that they know what is their
knowledge world is there an shared
emotional state that they have if it’s
computer programmers that are beginners
they’re probably like they’re probably
anxious they’re probably like
uncomfortable like wondering if they’re
ever gonna be good enough on the other
hand if they’re developers that are like
have been working with computers for
twenty years plus then then they know
that they are not never going to be good
enough so they are cool about it any
communication be it technical
documentation like a comment in a code
base be at a chat message to your
partner or romantic interest be it a
medium article be the book be it
lunch conversation at work all
communication in order to be effective
needs to be crafted whether its target
audience in mind I’ve run across a
couple of people in my career that does
this really well that I look up to a lot
and superficially they might come across
as you know nice and polite people and
they are I suppose but I think that
viewing them as such trivializes what it
is that they are really doing and what
they are doing is paying attention to
who their target audience is and
understanding them before broadcasting
their message to them you can recognize
these people because they are often they
even in cases when they have a message
to bring to you or to a group they are
not the first one to speak they spend
some time with you and I’m talking to
you asking questions about who you are
and where you are coming from and
understanding your needs before they
start talking about what they’re there
to talk about because they always craft
their message for your needs so to speak
and this makes them extraordinarily
effective communicators because they
have optimized their message for the
recipient so they don’t communicate with
general messages that are crafted to be
understood by everyone and thus not
effectively understood by anyone so
instead they just it worked with more
specific targeting of messages
understanding who they are talking to
they prefer to talk individually to
people when but when they need to talk
to a group they try to narrow down the
group and understand that group of
people before before starting their
communication or writing that article or
whatever a distant
doing so you cannot achieve more clarity
in your communication by removing
civility because civility understanding
your target audience and respecting your
target audience and adapting yourself
your messaging to the target audience is
a huge part of achieving clarity so the
next time you’re about to tell someone
that they are wrong spend a little bit
of time with the person with the third
market understanding where that where
they are and why it is that that they
think this way before you start
communicating that way your message has
a much much higher chance of being
received on and and understood because
if it isn’t received and understood and
agreed upon then it’s basically just you
shouting in through the void really did
any of this make sense do you have
thoughts on this let me know in the
comments or if you are a patron of one
phone function let me know one fun fun
forum there is a link to a topic for
this specific episode in the episode
description in case you are new you have
just watched an episode of fun fun
function I release these every Monday
morning or wait hundred GMT so that you
don’t forget that you can subscribe here
and eternal notifications in the app if
you want to or you can just watch
another episode right now by clicking
here I am mpj until next Monday morning stay curious
Please follow and like us: