The document provides guidance on marketing open source projects. It discusses defining marketing as capturing attention and resources in a crowded environment. It recommends identifying customers and their problems, developing quality code, documentation, and various types of content like blogs, videos and books to teach users. It also suggests participating in communities, conferences and social media to generate traffic and foster conversations in order to attract critical resources like users and contributors to open source projects.

1. Welcome to “Marketing your open source project.”
1

2. Some things you will learn in this talk include what marketing is, and isn’t.
Why you need to do it. And how to do it. All of this specifically for and about
open source projects and communities. I may run out of time for questions
within the session, but please feel free to grab me afterwards for a hallway
chat.
2

3. Why should you care about what I have to say on this topic? 30 yrs,
communicating & helping others communicate about technology.
Some jobs have carried a marketing title, others have not, but most
have been about “content”. You may know me from YouTube,
blogs, or social media. book I co-authored 25 years ago called
“Publish Yourself on CD-ROM" although nowadays the books I edit
are better known.
I’m now ... My specific qualifications for this job include...

4. I’m part of a team of evangelists and marketers focused on open source at
Amazon. Part of our role is to provide connections into open source
communities. We also act as consultants to other teams at Amazon on how to
do open source, & how to manage and interact with communities. We help
with launches of OS projects – Amazon Corretto, Firecracker, Open Distro for
Elasticsearch. My job is to tell the world about what Amazon does in open
source, via the AWS Open Source blog and social media. That’s plenty about
me, now let’s talk about you.
4

5. 1989 Kevin Costner movie “Field of Dreams” – man who builds a baseball field on his
farm in Iowa, because a mysterious voice tells him that, if he does this, something
magical will happen. Many developers think (or hope) that this also applies to
technology: that building great code is enough. Many projects, and even a few
companies, have operated on this assumption. Costner does get a magical result: he
ends up with a field full of baseball-playing ghosts. You also may be lucky and
magically get a lot of attention to your project. But this happens rarely. Even if it
does happen for you, keep in mind that, if you leave it up to others to talk about
your project, they may get it wrong. There is no one more qualified to talk about
your technology than YOU. So you should be the one to lead that conversation.

6. Let’s take a step back and define what we mean by marketing. Here is a very basic
definition, in which marketing is about getting people to exchange their money for
your goods or services.
Many technologists believe that marketing contributes nothing to a real
conversation about technology. At worst, they assume that marketing is
deliberately misleading or manipulative. Yes, this can be true. But it doesn’t have to
be.

7. Even if you don't have a _bad_ opinion of marketing, you may be thinking that you
don't need it: “With open source, I’m not selling anything, so why do I need
marketing?” You may not be asking for money. But you are asking people to give their
time and attention – which are very valuable commodities – to support your ideas.

8. So let’s try on a new definition of marketing. In open source, marketing is about
getting people to exchange their time and attention (and sometimes money) for your
ideas.

9. Maybe at this point I’ve convinced you that marketing might be useful, but
you’re wondering: “Do I really need it?” Consider the following.
9

10. As you can see, the number of repos on GitHub is huge and growing. That is
the environment in which your open source project is competing.
10

11. So, to expand our definition of marketing yet again: marketing open source is about
capturing scarce attention and resources in a very crowded environment.
What kind of resources am I talking about?

12. The main resource you need is people, ie users and contributors. People may
make contributions to a project entirely on their own time, but more
commonly nowadays, they are assigned or even hired to work on a project
by a company. Either way, people are your primary resource. The other
resource a project may need is money, or the things that money can buy,
which includes people’s time to work on it. So, yes, money does come into
the equation even when the thing you’re marketing does not have a price
tag.
12

13. Now let’s talk about what you can do to start attracting some of those critical
resources to YOUR project.

14. Amazon operates according to our LPs. We take them very seriously, & the first &
most important states that we start from the customer. You can apply this principle to
any project or product. Your first step should be to identify your customer: who is this
project designed to serve? Then get very specific about the customer problem you’re
going to address, & how. A framework you may find useful is Amazon’s PRFAQ,
which is a press release you write for the project before you ever start coding on it.
This should focus on the value of your project TO THE CUSTOMER. Questions about
execution are answered in FAQs that you can also write up, but the main focus of the
document should be the customer & their problem you’re solving. As your project
matures & grows, for every change, patch, or pull request, ask yourself: how will this
serve the customer? If you’re not sure, talk to them. Always be having those
conversations.

15. Only after you have identified your users and their needs are you ready to move on to
actual coding. I’m not going to say much about the code because it’s the part that is
most often done well. I do recommend that you try to architect your code for
participation and to lower the barriers to entry. For example, design with documented
APIs so a contributor can write a module that plugs in without having to understand
the entire codebase. Comment your code so that, if someone does need to read it,
they have a better chance of understanding it. In addition to the basic code, you
should provide tools, tests, and examples and sample code.

16. Many projects stop right here: “Here’s the code, have fun! Why doncha submit a PR
sometime?” Well, no. You need more than code. This checklist from GitHub is a
useful reminder of the basic bill of materials that you should include with your
project upon launch.

17. But you can and should do more. As an example, for Style Dictionary, an
open source project from Amazon, my colleagues Danny Banks and Charles
Dorner went well beyond those basics.

18. Good documentation is crucial, and it may be the most difficult thing for a
project to achieve. Technical writing is a very different skill from coding; people
who are good at both are rare. But documentation is also the most important
thing, after the code itself, that you can do to attract people to your project.
You must make good documentation happen for your code. I know it's not
easy. I have been in conference sessions discussing the eternal problem of
documentation, and the answer some projects came to was to pay an expert
to do it. Which is a perfectly valid option.
18

19. Bonus points for looking good: stylish
documentation is easier for humans to read and absorb.
19

20. But “good” documentation is not enough. What you really need to do is help people
understand what a technology is about – and how they can use it to kick ass. I
learned this years ago from Kathy Sierra's wonderful blog, “Creating Passionate
Users.” She said: Don’t tell users how awesome your product is – tell them how
awesome THEY can be using it.” Better yet, TEACH them.

21. Many different kinds of content can be useful in teaching people about technology;
this list is not exhaustive, but these are ones we’ll go a little deeper on today.

22. There are a lot of different terms and styles of technical papers, used differently at
different companies, and they’ve all evolved over the years. Don’t get hung up on
the terminology, just think of a general category of deep technical content which
could include use cases, architectures, how-to’s, etc. This might be shared as a
blog post, a paper, or a conference talk. It should be rich and deep. My experience
with the AWS Open Source blog is that our audience has a big appetite for deeply
technical content, and they love hands-on exercises. One of our more popular
recent posts was 4600 words about Running Open Distro for Elasticsearch on
Kubernetes, written by a security engineer at Ring. Again: don’t just tell people
that your technology is great, show them how they can kick ass with it!

23. Yes, you should definitely have a blog. Types of posts may include technical deep
dives, release announcements, events, news snippets – whatever is important and
interesting to your audience. There is no canonical length for a blog post – use the
words you need to cover the topic, no more and no less. If you’ve got a lot of text,
break it up and make it visually interesting with graphics and headings. Keep in
mind that blogs were designed to be chronological, which is not the best way for
readers to locate specific information. Use elements like categories and tags to
help them navigate.

24. Video is a popular way to share knowledge, and many formats and topics
are appropriate. However, the vast majority of users don’t get past minute 3
of any video, so keep it short. Put it on YouTube for findability. Subtitles or
captions are great for accessibility and also to help with comprehension
among people who read a second language better than they speak it –
which is true in a lot of the world.

25. Getting coverage in the trade press, both print and online, can useful. You may
want to get professional help on this, because anything press-related is more an
art than a science. Press relations is actually a lot about press relationships.

26. These are NOT beasts that you can easily harness to your marketing needs. Trying to
game them is risky and usually counter-productive. But they can drive a lot of traffic
and discussion. If your project ends up on Hacker News or Reddit, you should
monitor whatever discussion is going on, and be prepared to step in – carefully.

27. For some projects and technologies, articles in refereed journals may be appropriate.
Be aware that even a short article for one of these can be a lot of work.

28. Books are a great marketing tool, and possibly a career boost. But be aware that a
book is an insane amount of work, may go out of date pretty quickly, and not all tech
books are successful. Even the successful ones don’t make much money – certainly
not enough to cover the time you put into them. Yes, that’s a new book from Brendan
Gregg and, yes, I edited this one, too.

29. A logo with personality is a great asset. You can make it into stickers, t-shirts, and
other schwag, which people will want even if they’re not using your thing –and that’s
free advertising! This is the Style Dictionary chameleon. Other good examples are the
Docker whale and the GitHub octocat - all of them are cute and extensible.

30. Days-long classroom training is not as common as it used to be. It’s been replaced by
online, interactive, video-based courses, and shorter tutorials that might be given in
half a day or a couple of hours, say in conjunction with a conference. All of this is
good to have – again, it’s all about helping your customers learn how to kick ass
with your technology.

31. When you set out to create various kinds of content, keep in mind how much time it's
likely to take. My source for this is my partner Brendan Gregg, who has done most of
these, and, being a performance engineer, he measures things.

32. All this may be feeling a bit daunting – you may be wondering how you can
even get started. Here are some shortcuts, places to look for inspiration and
answers to help you develop useful content, or at least figure out what
questions people are asking.
32

33. So, now you’re creating all kinds of content, you need a place to put it. Here are some
options.

34. You also need to drive traffic to it, and, over time, you will likely find that most
of your traffic comes from search engines. So you'll need to know something
about search engine optimization. It's an arcane art, whose best practices
change constantly. Very broadly, getting attention from search engines
involves creating lots of relevant content, with the right keywords, and keeping
it fresh. code and documentation count a lot, but other material helps.
34

35. You can help both search engines and people find what they're looking for
by using keywords, tags, and categories as available on whatever platform
you're using.
35

36. Meetups, talks, and conferences are useful both to generate content and to share it.
Think of your presentations as content. Use the same tools and techniques to drive
attendance and awareness to them as you would for anything else.

37. Social media is useful for getting traffic to projects and content, and for fostering
conversation. Which channel is best? As always, it's about the customers: go
where your audience is.

38. Again, go where your community is – every community is different in its
communications preferences. You need to keep an eye on any forum where your
project is or might be discussed.

39. You could leave this talk right now and you'd have gained some useful knowledge.
But since you're still here, I'm going to let you in on the secret that has guided most
of my career.

40. The secret is: everything that touches the customer is marketing. EVERYTHING.

41. Think about air travel. Every touchpoint and interaction around an airline trip
affects your overall satisfaction, and there are many opportunities for someone to
screw it up and ruin your day. The same is true for your project. The experience of
your open source project includes every piece of code, content, and collateral, AND
ALSO every interaction, with every person involved. It ALL matters.

42. A healthy community is an important part of the overall experience of your project.
You need a code of conduct, and you need to enforce it. Diversity matters. Open
source is even LESS diverse than tech overall, and we are all missing out on
potential contributors, which is a stupid waste of talent. Some communities have
been successful because they have worked from the beginning to be inclusive. Also
think about diversity of contribution: does your project value and recognize other
kinds of contribution than just code? Responsiveness: If someone asks a question or
reports a bug or submits a pull request, do they get an answer quickly? And is it a
kind answer? Related to that…

43. Do NOT tolerate brilliant jerks in your project: they are not worth the damage
they cause.
43

44. Let's go back to this definition: I said that everything that touches the customer
is marketing. Now think it through. If everything that touches the customer is
marketing, then... the question is...
44

45. 45

47. My colleague Charles Dorner for the materials and insights on some of these
slides.
My partner Brendan, because we always help each other with our talks, and
he helped a lot with this one.
My friend Laura Ramsey for paving the way in marketing technology and
open source, and sharing stories of how it was done at Sun long before I got
there. And also for direct help and ideas for this talk.