Yesterday I gave another presentation to the VMware OSS maintainer’s group with my usual co-presenter, Abigail McCarthy. For this month’s presentation, we spoke about how to attract more technical writers to your open source project.

Abigail’s part of the presentation was the second half and she did a wonderful job sharing strategies for working with technical writers once you have them volunteering for your project.

I’ll share my half of the presentation here.

Have you ever wished you could make a clone of yourself just so that you could finally tackle all the work you need to do? Those of us who work in open source often feel that way a lot. We frequently find ourselves in the situation where there is a really large amount of tasks that need to be done (or should be done) and not quite enough time to get it done.

That seems to be especially true of documentation work. There’s just no end to all the new content you could create or the existing content that could be improved.

But the good news is that, at least in theory, your community can help you with that.

To illustrate my point, allow me to use myself as proof that this is true. I joined the Salt Project as a technical writer about a year ago. The Salt Project is a VMware sponsored, Python-based open source project that has been around for about 10 years and has had about 2,400 contributors over that space of time. When I came on board, I was their first dedicated technical writer and so hopefully you can imagine what 10 years of documentation for a pretty complex tool with 2,000 contributors looks like. Needless to say, there’s a lot of work to do!

And yes there have been times in the past year when occasionally when the sheer scale of the work that needs to be done truly feels overwhelming. But one of the real bright spots over the past few months has been a sudden infusion of new community members joining our Salt docs working group and beginning to make meaningful, long-term, strategic improvements to our documentation. So… wow! Right?

Just in case you don’t believe me, here’s the details! Our docs team consists of me, who is the only VMware employee, and several volunteers from the community.

So how did I get so lucky? How did we get here? And how can I spread the good fortune to all of you so that you can also have a vibrant and “sticky” community that not just adds to your workload, but actually helps you with it? Well, stay tuned because that’s what this talk is about!

Abigail and I will talk specifically about how to attract technical writers to your project and work with them effectively once they join. But I’m confident many of these same principles can apply generally to attracting any kind of role or type of community member that you want to attract to your project.

But first, let’s do some myth-busting about tech writers. The first myth I want to bust is the idea that nobody wants to work on the documentation or that technical writers don’t want to contribute to open source projects.

As Rich Bowen, put it:

There’s common wisdom in the open source world: Everybody knows that the documentation is awful, that nobody wants to write it, and that this is just the way things are.

But the truth is that there are lots of people who want to write the docs. We just make it too hard for them to participate.

So let’s bust that myth a little bit. Because I’ve heard people express that sentiment or belief before. But I really don’t think it’s grounded in reality.

At Abigail’s suggestion, I conducted a really, really scientific poll on Write the Docs a few weeks ago. Write the Docs has a Slack community of 18,000 members who are passionate about or interested in documentation in some form. In my super, super scientific poll, I asked this group on the general channel how many of them would be interested in contributing to an open source project as a technical writer. 66 people responded and exactly 0% said they would never contribute to an open source project.

So, yeah, writers are out there and they are willing to help.

And this matches my personal anecdotal evidence as well. Because in my evenings I contribute to The Good Docs Project, which is an open source project devoted to improving documentation in open source and beyond. And we have a community of 40 active contributors and an additional 60 past contributors to that open source project.

So technical writers are definitely out there and they want to contribute to open source projects. But as Rich Bowen says, we just need to help them to participate.

One great place to start is to figure out what motivates technical writers to contribute and how you can use those motivations to attract them to your project. That means asking yourself what are the personal and professional goals and motivations that many technical writers have and how can these writers meet those goals by contributing to your project specifically.

I do a lot of personal study into how to help open source communities succeed and I also just have a lot of personal, lived experience about what works and what doesn’t work to attract technical writers to a project and to get them to stay long enough to make a meaningful contribution.

In general, when it comes to attracting people to your project, you need to have clearly defined goals or a set of tasks that you have in mind for technical writers to work on. And you need to work on your elevator pitch for why a technical writer might want to work on that set of tasks. People will usually come to your project if they think they can make a meaningful contribution in some way, but also if there’s some benefit to them.

Oftentimes, technical writers are attracted to a project because they want to improve their technical skills, writing skills, or leadership skills. Or it could be that they are genuinely curious and find the tool or project interesting on some level. Or it really could just be that the project seems like it has cool people that would be fun or interesting to work with. The key is to always experiment with new pitches until you find something that works, until you find your project’s “X factor” that seems to really get people interested in knowing more.

For me, I have a lot of success attracting aspiring technical writers who want to develop practical experience in the field while being mentored by a more experienced technical writer. I also attract experienced technical writers who have recently been laid off and want a project to keep their skills up and stay connected to a network.

So my best advice is to be flexible, to always listen and keep a pulse on your community, and then to make adjustments based on what works and what doesn’t.

One thing I want to emphasize when talking about why people contribute is that most people contribute to open source for a complex mix of intrinsic and extrinsic motivations. It’s pretty rare to find people who are 100% motivated by purely altruistic reasons. They instead tend to be somewhere on a spectrum.

I once got into an argument with one of my fellow Good Docs community leaders as we were developing the personas for our community. He didn’t like that I had indicated one of the goals of our contributors might be to get a job in technical writing and to build their professional writing portfolio. He said to me that if people have selfish reasons for contributing to our project, that we shouldn’t want to attract those people to our project. And my rejoinder to that was that, well then, nobody would contribute to our project and if we were to set up that kind of purity test, nobody is going to pass it.

I do find that purely extrinsically motivated people tend to not stick around for long to begin with and there’s a lot of research to validate that. Plus, there’s research that shows that purely extrinsically motivated people can sometimes be a toxic drain on your community. But also I want to mention that a lot of people also might start out slightly higher on the extrinsically motivated side of the spectrum when they first join your project and then find that their motivations become more intrinsic over time—kind of like what the t-shirt in this image on my slide illustrates. A lot of people in my projects initially join to improve their career or skills in some way and then end up staying for the community—for the friendships and sense of purpose that they develop here.

I like a quote on that topic by Mary Thengvall.

She says:

It’s also important for there to be a sense of commitment and care for each other, even if that care is as broad as wanting each other to be successful in their programming ventures. This care leads to a desire to help each other—to mentor, encourage, and offer assistance where possible. This increases the “stickiness” of your community, ensuring that people who come are far more likely to stay.

I like especially says about helping be successful in their programming ventures. I want make a quick sidebar about that our project started offering regular Git Training workshops on about a quarterly basis in our community. We initially started doing this in order to help the technical writers to have skills we needed them to have with Git in order to contribute to our project. But it turns out that it’s a pretty good recruiting tool too because we offer this Git training workshop and in exchange they make a commitment to make a long-term contribution to our project. And a lot of technical writers are interested in getting that kind of Git training.

So, all right, if you do what I’ve said so far, you’ll develop your project’s elevator pitch, tailored to the general motivations of technical writers. Great!

But where can you go to actually find technical writers so that you can make your project pitch to them? The best place to pitch your project to technical writers is to hang out where technical writers hang out. That includes the online forums, social media, and also in-person meetups and conferences where technical writers are likely to be in attendance. And then I try to put on my extrovert hat and push myself to engage and meet new people.

For technical writers, one of the best places to hang out is the Write the Docs Slack workspace, but I also sometimes post and contribute to the technical writing subreddit and other similar forums. I make it a point to casually interact on these forums and keep an eye on the pulse there

Every once in awhile I get a golden opportunity where someone asks how they can break into technical writing as a new writer, and that’s when I jump on it. I always share a blog post where I explain how contributing to open source is a great place to build their portfolio and grow their network as a new technical writer. And then I mention they could reach out to me if they want to get more involved.

Also, sometime people on those forums asks if there are any good open source projects that are looking for writers, I always try to make a comment on those posts. So a lot of times, these kinds of opportunities organically come up.

For in-person events, it’s always good to attend local technical writing meetups if your area hosts them. I try to never miss the Writing Day portion of the Write the Docs conferences. They hold three conferences a year throughout the world and their events usually feature an all-day Writing Day where you can set up a table and invite people to help you with your project. Those single events are responsible for about 75% of the people who join the Good Docs Project community and the other 25% tend to come to us from the Write the Docs Slack workspace. But we’re also getting to the point where we’ve generated enough buzz and name recognition that people are now starting to send people to us.

So, that’s how I usually meet writers for the Good Docs Project. For the Salt Project, a lot of times I’ll be recruiting for the Good Docs and I’ll mention my other projects and sometimes those writers will say: “Yeah, that’s nice about the Good Docs Project. Now tell me more about Salt!” So, I’ve been almost accidentally attracting writers to the Salt Project that way. And now that we’ve built up a momentum, it’s starting to attract more folks because they can see the value proposition now. They see that in exchange for their time and energy helping us with our documentation, they in return get valuable mentorship and literal skill training such as how to work with Git for documentation.

So, that’s how to attract technical writers to your project and begin building momentum. It does take some time and you don’t always see progress at first, but I find that there’s almost always a tipping point where once you have a core group of people, you start to attract even more people to your project and it builds from there. It takes time and patience, but you’ll get there soon.