Beyond code: how content helps open source projects thrive

One of the best things about the open source community is that anyone can have an impact, regardless of skill set, geography, or experience. From lending software development expertise to designing artwork, translating docs, and evangelizing projects, trust me: there’s a project and community that’s waiting for you.

Stephanie Morillo* has carved out her niche as tech writer, editor, and content strategist, channeling her energy into non-coding roles, from co-founding #WOCinTech, which connects women and non-binary people of color in technology, to helping the Ruby community improve its documentation quality.

Ahead of her talk at All Things Open, she shares her experiences, advice for creating high-quality open source documentation, and perspectives on the importance of “non-coder” contributors.

*Note: she also happens to be my teammate, partner in crime, a true content guru, and all too modest about her Ruby abilities.

Q: Tell us about yourself – how did you get into tech writing?

Initially, I thought I would take my writing skills and become a developer. After I learned to code, I started considering a few developer jobs – but, while I liked how coding forced me to learn how to be patient and approach problems in new ways, it wasn’t what I liked most about technology.

What I liked most was documenting what I was learning. When the friend who taught me Ruby suggested that I blog to share my learning process, I started researching companies who were looking for people who liked writing and were interested in helping and communicating with developers. That’s what brought me to Microsoft a couple months ago.

I’m still active in the Ruby community, where I focus primarily on writing and content. I’m a maintainer for Bundler, the dependency manager for the Ruby programming language, and always analyzing how our documentation performs and looking for ways to improve our docs.

Q: Tell us about #WOCinTech Chat. What prompted you to start it?

I co-founded Women of Color in Tech Chat (aka #WOCinTech Chat) in 2015. At the time, I was getting deeper into the technology space and attending a lot of events. As a woman, and a woman of color, I felt like I was in the minority of the minority in the room, which was both isolating and made it challenging to build a strong, supportive community. I’d worked in New York City for most of my life, and I found it disconcerting that New York City tech companies weren’t reflective of the diversity in the city that they called home.

I became friends with a woman named Christina Morillo – same last name is a fun coincidence – and we decided to host a Twitter chat to see if anyone else felt the same and was interested in building a community. The wonderful thing about Twitter is that it connects people, no matter the geography. So, we started as this Twitter chat and, then, when we got a bit of funding, we evolved it into a broader initiative: creating newsletters with job opening roundups, funding conference tickets for women of color interested in specific technologies, and more.

One of the biggest things to come out of #WOCinTech Chat – and one of the things I’m most proud of – is a collection of free stock images. Christina and I were building our website and noticed that there weren’t many stock images of women of color out there. So, we created a free stock image repository, featuring women of color technologists across various roles, from software and UX designers to tech entrepreneurs. We knew we wanted to allow as many people as possible to use the images, so we released via Flickr and invited the broader community to use them for free. We’ve seen these images popping up in many places, from media outlets, like The Guardian and TechCrunch, to company marketing materials and conference slide decks.

#WOCTech images on Flickr

We released three years ago, and we’re still seeing them in circulation. Plus, perhaps more notably, it’s encouraging to see companies who’ve been inspired by the photos and are producing more diverse stock collections of their own as a result.

Q: We always hear about “quality documentation,” but what does that actually entail? How can open source maintainers and project owners improve their docs to help new and existing contributors?   

There’s no one singular content strategy. I like to think about it as different tactics that open source maintainers can mix and match, depending on the community needs and the size of their projects. A good first step is for maintainers to learn what content already exists, including what documentation they’ve already produced. For some smaller projects, that might be just a couple of pages. For bigger projects, which have potentially gone through multiple release versions, the scale will be much different, but finding out what content you already have is still definitely important.

Then, a maintainer needs to assess the state of all the various content pieces: What’s outdated and needs to be removed? Are there things that we can perhaps combine to make it into something bigger? What’s missing? What kind of documentation don’t we have that we should have? Are people asking questions or opening bug reports for things that aren’t actually bugs?

Next, you need to ensure that your documentation is public. To start, this can simply be a separate repository or a wiki for smaller projects. For larger projects, creating an external site where people can go and access your documentation is essential for discoverability and navigability. This is valuable for everyone: it’s easier for contributors to search and find the information they’re looking for, since sites are typically optimized for their end users, and project maintainers and owners can collect site performance analytics to find trends and continuously improve.

I also encourage maintainers to create templates and canned responses. If you’re a project maintainer and you’ve written a how-to guide, templatize it and put it somewhere in your repo, making it easy for contributors to know your expectations before they contribute to your project. When they’re writing their own docs, they’ll know they don’t need to reinvent the wheel every time and that there’s a consistent format you’d like to follow.

I’m also a big fan of reiterating that contributors are welcome to edit information on the docs site. If they see something that should be added or changed, they should be able to go directly into that page and make changes themselves. Maintainers create flags to let contributors know that, yes, we encourage (and need!) you to actively make this better with us, not just flag problems.

Q: Are there any common issues when it comes to open source content management?

A big challenge is not understanding how to apply project management to content. In other words, you need a broader frame of reference or content project plan to help guide how, when, and why you’d like contributions from community members.

It’s common to see a blog post or documentation about the building the software aspect of an open source project, but it’s not as common to see the same thing when it comes to building the documentation and managing content.

We should think of documentation as a product in and of itself, not as simply an artifact created from the engineering process. It demands a product-like development life cycle, and we’re starting to see more and more larger projects, like Vue.js, embrace this mentality: it’s evident that they have a structured content management process.

Q: What are some of your tips for finding good writer contributors for open source projects?

First, figure out what kind of writing you need. There are different types of writing – copywriting, technical, UI/UX writing, etc. – and different writing types require different skill sets. For example, if I need API documentation, then I should look for somebody who’s a strong technical writer. But if I need somebody to write the words on my project’s website, a copywriter might be a better fit. Somebody with more copywriting experience might not have (or need) as much technical background, and vice versa for the type of writer you’ll want to author your API docs.

A second piece of advice: go where writers are. The development community is huge, and then there’s the technical writing community, but we’re just starting to see some intermingling. So, it’s important for developers to start making connections with people in the technical writing community (and the same goes for those who create technology-focused content). Personally, I recommend going to a Write the Docs event, but if you’re unable to attend in-person, check out the Write the Docs Slack channel  to “meet” tons of technical communicators from several tech companies.

You’ll find members talking about things that benefit not just the writing community, but also developers, especially with respect to bringing non-coding contributors to open source projects.

And, this is something that I personally would like to see happen more and more. All of my open source contributions are technically “non-code,” but documentation is just as important as bug fixes and new features. They complement each other, and both are essential to help projects and communities grow and thrive.

If we start recognizing where the holes are and encouraging people who don’t necessarily have an engineering background to get involved, we’ll make our open source communities that much richer, inclusive, and accessible.

Follow Stephanie Morillo @radiomorillo. Check our her blog to learn more on the above topics. 

Questions? Let us know in the comments below.

Lacey Butler

Lacey focuses on open source community engagement and is the co-producer of The Open Source Show. Her goals: recognize, inspire, and motivate developers far and wide, helping them do amazing things with technology. When she’s not crafting new shows, you’ll likely spot her at the public library searching for new gems or trying every product Trader Joe’s has to offer.

See more articles from this author