foreign
[Music]
good morning and welcome to day two of
everything open where we are going to
hear about boosting your Project's trust
signals with great docs from Felicity
brand Felicity is a technical writer and
editor who is passionate about open
source and is a firm believer in the
power of non-code contributions to open
source
yeah
[Laughter]
Felicity will be talking about the
benefits to your open source project of
having great documentation please make
her welcome
[Applause]
all right I've got my mic on
hi welcome thank you for coming
so today I'll be talking about how to
boost your Project's trust signals
with great Docs
so I begin today by acknowledging the
traditional custodians of the land where
I live and work and on which We Gather
today the warandiri people and I pay my
respects to their Elders past and
present
so I also just need to pop my public
speaking stress bubble if we're not
making mistakes we're not learning so
I'm allowed to make mistakes everyone
okay
um I want to explain that I've used the
term docs in my title very broadly
I mean docs yes but I also mean much
more than documentation I'm talking
about any kind of content or language
used in and around your project
So today we're talking about trust
signals
how you can broadcast informational cues
to help make
I've made a mistake gang
our first one okay
I've got to go back
to
my slide number
g'day
I'm Phil citybrand AKA flickster
I identify as a technical writer I call
myself a technical Communicator I work
as a communications consultant
um I work at open strategy Partners I do
a lot of writing and Technical editing
mentoring writer enablement and training
so I discovered open source pretty
recently in 2019 when I took part in
Google's first season of docs you may
have heard of their summer of code it
was a similar program but for technical
writing
and that's where I discovered I'm
intrinsically motivated so me and open
source are a perfect match really
the two open source projects I hang out
at typo III
which is an Enterprise open source CMS a
bit like David Hasselhoff really big in
Germany
I am a member of the association I
co-authored a book about that product
available at all good bookstores
um
and actually one of the association
board members is here at the conference
today so if you're interested let me
know when I can introduce you
so the other project I hang out at as is
called the good docs project I
co-founded that um where a team of
technical writers and developers
creating templates for open source
projects so we're still young and
growing it's really cool over there come
and join us if you want to hang out and
help us create Docs
there's a pretty cool working group
looking at trying to automate spinning
up a minimum viable dock set so if that
floats your boat come and say hi
so here's where I work open strategy
Partners or OSP
we're a Content marketing agency for
tech product and service companies
so why is trust a thing for me
as a tech writer
coming from working in large
organizations
where there is a tech department and a
marketing department they're very siled
right never the twain shall meet
and
now I work for a tech marketing agency
how do I sleep at night so OSP was
co-founded by two two Founders
Tracy Evans has a really strong
marketing and business background and
Jeffrey McGuire really strong in Tech
and Communications
and between them they focused on this
gaping Chasm this problem of buzzword
bingo that you get particularly around
marketing and Tech
so you might have heard this phrase
developers are allergic to marketing
and their counter to that is this
communication framework that we use
called
authentic communication and it it has
three main tenets of empathy Clarity and
Trust
and so the idea is that we write and
speak clearly and accurately about tech
we are producing a lot of content you
know we do a lot of writing about
technology
Technical Solutions features products
Services okay and we know that we need
to understand the tech to be able to
talk about it
we use empathy to understand our
technical audience
and to know what their challenges are
and that builds Trust
so trust is important if you want to be
a credible Authority
and if you want people to take action
which is basically what marketing is all
about
this is Francis fry
she gave her a well-known Ted Talk
famously worked at Uber she talks about
building trust and she says
you can only trust me and Trust what I'm
saying if what I'm saying has logical
rigor if it makes sense
and you can only trust me and Trust what
I'm saying if I'm being my authentic
self
if you can feel that I am being myself
and thirdly we can only we can only have
trust if I have empathy for you if I'm
putting myself in your shoes
and all that is to say that there's a
human element so say you've built a
fantastic Tech solution to a known
problem you can't just rely on the tech
speaking for itself there's a human
trust element at Play
So today we're talking about trust
signals how you can broadcast
informational cues
to help make that trust connection
as humans in the world we all make
decisions every day Guided by our gut
feelings based on our sense of trust in
a product or service
as an open source project owner or
maintainer if you gain a holistic view
of how your project presents externally
you can make informed mindful choices to
control and curate the message that
you're Broadcasting
and some of the most powerful signals
come from documentation content and
language
so here's what I want to cover today
what signals are why they matter
different types how you can influence
them and some practical resources
there's some interesting Research into
trust trust signals and how they
influence decision making
so what I really want you to walk away
with today is the understanding of how
you can influence signals that your
project is sending out and some tools to
help you get started doing that
so I'm going to talk a little bit about
trust I'm going to talk a lot about
signals and then I'll give you some
resources to help you get started
so what even are trust signals
they're visible cues that help you make
Rich inferences about the health culture
Vitality of a product or project
and they inform our decisions to take
action whether to download test
contribute participate and so on
and it all happens in the blink of an
eye we're all making big and small and
micro decisions every day
everything is giving out signals
but so just to try and put some scope
around it here in this room today we're
talking about open source projects
it's good to know about your signals
because as a project owner or maintainer
or contributor you can get out in front
of them and control or curate the
message that your project is
broadcasting
and that's a good thing because then you
can achieve your goals
here's an example we've got some docs on
the left side there release notes readme
code of conduct
on the right we've got some numbers of
things Stars downloads
Community activity
so different things can be signals
and signals aren't positive or negative
in themselves they're just information
open source projects by their nature are
very open
um so there's a wealth of information
available to people when it comes to
evaluating and decision making you know
you can see the release history you can
see who worked on stuff uh I don't need
to explain open source to you
um
so we're going to take a look at
different types of signals in a minute
but I wanted to look at first I want to
look at why they matter
um why are we even talking about trust
signals
trust plays an important role in
decision making whether we realize it or
not
Stephen Covey wrote a book called Speed
Of Trust and he says work gets done
with and through people
there's nothing more impactful on people
their work and their performance than
Trust
and he breaks down elements of trust
into two categories competence and
character
so competence addresses the questions
can you solve my problem can you solve
it better than the alternatives
so that might be if you're evaluating
open source projects this code looks
okay there's competence there
on the other side character addresses
the question do your values align with
mine
do you have a diverse culture
how do you treat user data do you
communicate authentically
so that might inform your decision to
get involved in a community or
contribute to a project
so why are you here what outcomes are
you after with your project
um
let's look at a few scenarios of
decision making in open source
maybe you've built
a great solution that solves a problem
you want people to use it so maybe your
goal is downloads okay so Stephen
covey's trust model
the competence section people are going
to use your trust signals to decide
whether or not to use your code can it
solve my problem
another example maybe you just need more
people to help you you want to increase
contributions you want folks to decide
to engage with your project so you want
patches bug fixes merge requests
signals are going to tell people how
engaged the maintainers are how active
the project is
should they invest their time fixing a
bug
and a third example maybe you want to
grow your community so now we're looking
at Stephen covey's
character trust traits What type of
community surrounds this project are
they organized welcoming inclusive do
their values align with mine
so whatever your goals there are things
you can do to
control or curate your signals to help
you achieve them
we're going to take a look at exam at an
example
of trust signals in play
so this is a very general staircase to
contribution each of the steps on this
staircase
will have Associated signals that
influence decision making to keep people
stepping along the journey
so let's imagine a simple example of
contributing a bug fix to a project
starts with attention so maybe there's a
social media post or Word of Mouth
so next comes interest I have that
problem that's interesting to me
now we're starting to look at signals I
look up the project I find it on gitlab
I read the readme
next comes trust in the technology so I
download it I try it it works it solved
my problem yay
but
there's a bug
whoa I don't know do I invest my
precious time in fixing this thing is it
worth it
okay so maybe I decide to spend five
minutes looking around the repo
I can see issues are being responded to
people seem to be talking to each other
in a rational manner
maybe I dig a bit further oh they've got
a feature roadmap okay that's cool so
people are using it patches are getting
put in there's some kind of future plan
okay I've decided I'll contribute a fix
now I just need to find out how to do
that
do they have a contributors guide no
that's okay
it's covered in the readme okay there's
an issue template great so this project
is organized it's active it solved my
problem I'm going to contribute a patch
and you know what maybe I'll stick
around and see if I can help anyone else
so that's one example
obviously there are other examples and
different signals will be associated
with different Journeys so um
yep that's all I wanted to say haha uh
so different staircases for different
um
user Journeys uh
like downloading or
joining a community different signals
are going to be important for those
parts
all right so we're going to take a look
at types of trust signals and there's
two types spoilers
um Sue
we've got some direct signals
the highly visual visible Clues so I say
that because they're usually built into
a user interface if you think of GitHub
or gitlab
lots of numbers on the landing page for
any repo so these are quick and easy to
consume
and they make an immediate impression so
looking at these they're almost
quantitative there's a lot of numbers
there
and you might use these direct queues to
make quick decisions about the quality
or the current state of play of a
project this code looks okay
I'll install it and move on with my life
the next set by contrast are indirect
you have to work harder to glean
information from these signals so
they're inferred from browsing through
content
they aren't Quant they're much more
qualitative
normally found in docs in issue threads
in conversation content and language
so people can gauge the tone of the
community your cultures and attitudes
around things like respect inclusion
diversity accessibility
and you might use these indirect cues to
make decisions from a longer term
perspective is this project worth
investing my time
going back to Stephen Covey do their
values aligned with mine
will I participate will I contribute
will I engage
so if you haven't been paying attention
until now here's a good time to tune
back in
um
an important attribute of signals is
their production cost
signals that are costlier to produce are
considered more reliable because they
are harder to fake
this principle comes from signal Theory
and it applies across Fields like
biology and economics
so in our example of an open source
project
it might be that you could get a bot to
artificially increase the number of
forks of stars on your repo
so although those signals are highly
visible and quick to consume
hey this Project's popular
they're not going to be as persuasive or
carry that same weight as an indirect
signal things that are costlier to
produce like documentation so a high
quality readme
takes a little bit of time and effort
and is a really powerful signal
being organized enough to have clear and
useful labels on your issues that takes
time
so there's a high production cost for
those indirect signals but they have
more meaning and they're considered more
reliable
wow
so what does that mean it means you
should invest your time in improving
your indirect signals put the work in
now take some action get out in front of
your signals and control
what you're Broadcasting
and the investment you make into that
higher production cost will flow through
to impact your other signals
okay let's say you're sold
before you dive in uh
just need to point out that it's
important to know that context is
important
so the same signal can mean different
things to different people same signal
can be both attractive and unattractive
for example a detailed contributor's
guide might excite some new contributors
lose detailed instructions for them to
follow takes them to their happy place
or it might be totally off-putting to
other people at work uh too much process
overhead and high bar to participation
so what's meaningful is going to vary
from person to person and it depends on
your goals as a project what you're
trying to achieve what you think is
important
you might really love process it's how
you work it's what you value
and it's a trust signal so
that's setting expectations for a
newcomer
uh at this point I'll just mention chaos
um this is the community health
analytics for open source software a
project
at the Linux foundation and they're
focused on creating a neutral set of
reference metrics to analyze open source
Community Health
and health in this case plays into trust
and Trust signals
so that neutralness is kind of important
because different things can mean
different things to different people
based on their role and what they're
trying to achieve so check out chaos if
you're interested in diving deeper into
that
okay we finally reached the Practical
steps let's look at what you can do so
there are three things I'll talk about
one is doing an audit the second is
defining your values and lastly we'll
look at content and language
so in order it gives you an idea of what
your project signals are going to say to
a newcomber or an outsider basically you
make a list you decide what's important
to you and you think about what you're
trying to achieve
but where you where do you start okay so
to help you we're going to look at a
study this study was published in 2019
it has a long name the signals that
potential contributors look for when
choosing open source projects
and this study came up with a list of
key signals that people use to inform
their decision about whether or not
they're going to contribute to something
in this case specifically a GitHub
project
so this is going to give you some idea
of what to include in your audit
checklist it wasn't an exhaustive study
but you've got to start somewhere
and this is just about contributing so
um bear that in mind so looking at this
list
even if you think your project is pretty
well covered it won't hurt to do a quick
audit of what you've got and look for
opportunities for improvement
for example you might think or your
repos have a readme it exists tick
that's a direct signal so yay for you
but you know let's look deeper what's
the quality of your readme is it
structured what language have you used
that's an indirect signal and it's where
people are going to infer more meaning
about your project
so I did just want to touch briefly on
all of these so except for website I
don't want to focus on websites because
I don't think it's appropriate for every
project to have one leave that up to you
but read me it's a Project's welcome mat
people expect a standard set of
information included here the what the
why of your project how to install it
and use it contact information maybe how
you're accepting contributions if at all
popularity that's a direct signal it
turns out people actually care how many
stars you've got according to this study
popularity is important
um
it it can according to the study it can
imply high levels of contribution so the
way you would influence your popularity
is not really by docs it's more PR so
you'd probably be going to events giving
talks industry participation
so stars are important to you that's
where you can focus
looking at activity uh recency of
commits
distribution is there an even
distribution of contribution is it
always the same for you people that's
neither good nor bad it's just an
informational cue
average response time on issues that's
your direct signal and responsiveness
that's your indirect so
what they mean by that is conversational
threads any kind of language and
attitude how people are talking to each
other are they being snarky how people
are being treated
in that responsiveness
and number of open issues and unmerged
pull requests so that's your direct
signal because it's a number
um
and their reasons that's your indirect
signal so you may have loads of open PRS
open issues and that may be fine because
they all have valid reasons for being
open
and if that's indicated in the thread in
respectful language there's your
indirect trust signal
contributor guidelines so a great
contributor workflow reduces the
friction between discovering something
you'd like to fix and fixing it so it
doesn't have to be its own document can
be a section of your readme
as long as it's thorough
and this study found that for some
people the lack of any kind of
contributed contribution guidelines
gives an immediate negative impression
so that might be something you decide is
a priority for you bonus points for
non-code contribution workflows and
again that depends on your goals
Scaffolding in this study refers to use
of labels and templates for issues
templates for pull requests or merge
requests and this shows that the project
is organized it has structure
code quality obviously code quality is
an important marker for project use and
the way you can show that is by
embedding badges in your readme to
demonstrate that the code base is fully
tested
according to this study contributors
looked for readable well-structured code
with few dependencies
so that may be something that's
important for you
and Community tone so if you're browsing
a repo you're diving into docs issue
threads look at the language used in
those docs it's going to demonstrate the
social norms of the project
so if all that feels overwhelming I'm
just going to give a Shameless pug for
open strategy Partners we do offer a
trust and vibrancy signal audit service
where we will do all this hard work for
you
um
we'll analyze your project look at these
signals and give you a report on areas
that you can focus on
okay so you've done your audit what's
next before you take action you might
want to think about your goals think
about what you value
decide who and how you want to be
and you don't have to spend a lot of
time it doesn't have to be exhaustive
but it's going to help you make
decisions about how you write talk
communicate in your project
so a code of conduct is a really good
way to do this
code of conduct should not only state
the rules of the conduct but should
explain why they exist
for example we enforce these rules
because we want to accomplish these
goals
um
if you don't have time to choose your
values and document them check out the
freely available contributor Covenant
which is a code of conduct you can use
and is adopted by many notable open
source projects it's a really Light Lift
we'll set you up pretty quickly
so if you do that one thing when you
leave here today that's a trust signal
right there
all right the third thing uh you've done
your audit you've worked out what you
value now comes the hard part
no one likes working on ducks
except for me I'm a tech writer so ducks
are hard
make it easy on yourself get yourself a
whole bunch of templates
GitHub and git lab obviously have a
whole raft of templates they provide
lots of resources to improve project and
Community Health signals
if you're starting from zero uh
come to my projects the good my project
the good Ducks project
um
we have software and Community templates
to kick-start your docs they're written
in markdown they're in a git lab repo go
and help yourself
each template has a companion guide that
drills down and explains what to include
in each section
written and reviewed by Tech writers so
you can be confident you're getting
quality if you really want to nerd out
with other Tech writers check out write
the docs community
that's a free open community
and they have a massive slack workspace
with multitude of channels devoted to
Tech Solutions
and process about tech writing so if
you're interested in automating docs doc
says code documenting apis Pros linters
maybe you're learning Tech writing maybe
your managing writers go and check out
that Community because there's a wealth
of resources there and friendly people
to help you
so I've listed a couple of other
resources there that I like
um
and I've got links to all of these later
that I can share with you
um
so you can grab them for yourself if you
know of other good resources please
shoot them through to me because I
really like collecting this kind of
stuff
oh yeah
so you've written some really good docs
now you want to set expectations around
how you want other people to talk and
write in your project
so you can do this with a contributor's
guide and or a code of conduct
I really like how Symphony does this so
this is from Symphony um
they bake their language guidance into
their contributors guide
they have a great page called respectful
review comments and I encourage you to
go check it out it's basically guidance
for anyone who's reviewing code and
leaving feedback in their project and I
just wanted to point out these two
sentences to you because
they really pack a punch
um
the setting expectations really clearly
to anyone who's doing a code review in
their project
so firstly you don't have to be formal
great
and we don't expect you to have
error-free English
so you can make mistakes yay
so those two things right there are
making the reviewer comfortable
chillax we're not expecting perfection
the next two things make the receiver of
feedback comfortable
so don't swear that's a pretty easy rule
to follow
and be respectful so anyone who's
submitting a bug fix knows going into
the review process that they're not
going to get sworn at and they'll be
treated with respect
so those two sentences encapsulate so
much they're setting a baseline this is
the absolute minimum bar we at Symphony
need if you a Community member are going
to comment on someone else's bug fix
so I really like how they've done that I
do encourage you to go and check out
their contributors guide and just take a
leaf out of their book I think they've
done it really well
so you can go further
my animation you've said expectations
now you might like to help the community
meet those expectations and this is
probably more for advanced players okay
you can do this with a style guide or a
writer's guide it doesn't have to be
lengthy so this is an example from typo3
so that's a large mature project
there's a lot of content that gets
produced around that product
we got a couple of websites we've got
blogs we've got events presentations
obviously Docs
so typo3 has a guide that says
when you're talking or writing about our
project here's the way that we want you
to do it
here are the guidelines and rules that
we want you to follow and that's a trust
signal
because it shows that
people have thought about it
and they're cultivating their culture
they're cultivating the culture that
reflects their values and it makes
people feel confident and safe so if I'm
coming to this project new I'm thinking
do their values align with mine
and I'm looking at this and I'm thinking
huh actually they kind of do they're
organized they know what they care about
they have guidelines like unfollow
and we don't have to all share all of
the same values
um just enough to make a trust
connection and Trigger that decision
making
okay check it out we're almost wrapping
up so
this is what I talked about
be aware of what you're broadcasting and
you can influence the signals that your
project is putting out
so what I want you to walk away with
today is the knowledge that you can take
action there are things you can do there
are templates and resources to help you
so you can take stock of
how you're communicating your technical
competence and Community character
you can do a trust signal audit
articulate your values and put effort
into creating docs and using language
that reflects those values
and that will flow through to entice
newcomers to your project and
Happy Days
so I've listed all of the research for
this talk and the references and
resources I used on a blog post which
hopefully that link is not broken if it
is broken you can find that on the open
strategy partners website blog
and that wraps it up team thank you very
much thank you
thank you
thank you for listening I know that 40
minutes is a long time to pay attention
um and uh yeah please get in touch if
you want to talk more and if you know of
any other templates or resources please
please share them with me okay
okay fantastic thank you so much uh does
anybody have any questions for Felicity
I can see one
thank you so much for that
um looking specifically at one
particular class of people you might be
trying to engage if you have a project
that has plenty of technical
contributors and you're looking to
attract more documentation contributors
to or you know in in the rest of that
space to help go from we've got to read
me too we've got a really good readme
what sort of trust signals would you
advise that documentation people in
particular are looking for
that's a good one
well I mean I guess so you're asking me
about as well so as a technical writer I
would say I would like a writer's guide
but that's tricky if you're a highly
technical group of people you've
probably never put together a writer's
guide before
um maybe just a really great read me
would be in enough I guess a writer
would be looking to see that
people cared
about their dogs
without necessarily having the capacity
to do the docs but certainly in circles
I move in there are often Tech writers
and also young or new upcoming Tech
writers who are looking for open source
projects to contribute to so it's almost
like we need a matchmaking service there
um
to get them together
if I might give an observation here but
I participated in a project that
actually has from your assessment quite
a good set of trust
and we've managed to acquire a couple of
people who are interested in
documentation
and indeed very good at it one of them
wrote a style guide for us
but
they often feel somewhat lonely within
the team because very technical people
don't like writing documentation and
it's worse than that they often won't
even just hand it to the technical
people to handle in some
sufficient detail at least for those
technical those writers those people
with that writing inclination to be able
to turn it into lovely language and and
put it up on the website or in the repo
or you can read me and so on so it can
feel very lonely in an entirely
technical group to be the person with
the urge to document yes because you can
find yourself struggling to get people
to give you the content yeah in a form
you can use to tidy up and make pretty
Yeah Yeah It's Tricky
I don't have a good answer for that it's
the lot of the technical writer's life I
think and we all I suppose I can only
speak for myself we develop strategies
to try and combat that challenge
um
no easy answers um uh I would my advice
to a lonely
writer person would be to get involved
with the write the docs Community
because
then you can find your people obviously
um yeah it's a challenge yes I don't
know um I I see and hear and feel the
pain of that
um
yeah foreign
softwares have like a um like a Wiki
system or something built into them like
it helps go Wiki and all that
but I guess the question I've got is do
you prefer to have the documentation
with the code or separate it out and
tell someone to go visit the wiki so
would you prefer like using a whole
bunch of dot MD files or have a bigger
wiki page
interesting I would my my immediate
answer to that would be maybe do some
user research and find out how people
are consuming that information so um
and that would hopefully tell you
whether you want to put your effort into
putting docs on the wiki or some other
way so you need to find out how they
want to consume the docs I don't know if
I've really answered your question there
um
thank you Felicity amazing talk super
inspiring
um
you said you're really passionate about
non-code contribution hi me too
um what do you what have you seen works
best to invite and and cultivate your
non-code contributors
huh yeah I I've only ever had good
experiences so my limited experience
with
um open source project has been very
supportive and welcoming of non-code
contributions so I don't know if I know
the answer but I'm sure someone in this
room wouldn't
um of how to do that yeah I guess you
just need to somehow
well I guess the first thing to do would
be to
include a non-cone contributor workflow
in your contribution guidelines um
hmm
so well I'm part of a big open source
project and we have all of our
documentation online in GitHub and
people can submit bug reports and pull
requests to that as well is that the
most appropriate workflow for
writing contributions or is some other
workflow better
I would say yes if you've got some
dedicated people
actioning those
right okay so
I hear what you're saying okay so for
typo3 uh we have a similar setup so
we've got our docs and there's a little
edit on GitHub button on every
documentation page and
um we will occasionally see people
submit
um through that you may need to
um if I were you I would I would just
publicize that maybe make it really uh
known I know in typo3 we made a little
video about it we kind of got the head
of product to say this is what you can
do it's really great you know
trying to encourage people to do that
that comes with its own challenges as
well some of some of the issues that do
come through on
um you know submitting changes on docs
pages
aren't valuable sometimes um yeah so you
really do need a team at the back of
that
um
Yeah It's Tricky ducks are hard
yeah I just want to comment uh on what
Felicity said as well I mean in the type
of three Community we've had two
important things that have helped people
contribute uh and that is the edit on
GitHub button and having a documentation
team that takes care of the community
aspect of being a documentation
contributor that it is extremely
important because what keeps people back
often is the first step over the
threshold and actually doing your first
uh contribution just like with code
um
do we have time for one more question
Amy folks one more
well in that case
um would you all join me in thanking
Felicity once again peace
[Applause]