Two years ago, I attended Write/Speak/Code, a conference that aims to "empower women software developers to become thought leaders, conference speakers, and open source contributors". Over the course of three days, attendees listen to talks from developers that write about their work, speak at conferences and meetups, and contribute to open source, and they also sit in on workshops that give them the skills they need in each of those areas.
The final "coding" day was the biggest highlight for me. WSC provided a list of projects that were welcoming to first-time contributors, and the organizers made it clear that code was not the only valid form of contribution. As a beginner—and as one who loved writing first and foremost—it was important to be told that many projects out there have needs that extended beyond coding.
Since then, the projects I've contributed to have been ones that made it clear what their needs were, and how my particular skill set could help them meet those needs. All too often lots of projects make it known that they want writers or documentarians, but stop short of really articulating what kinds of writers they need, what type of documentation they need, and what information writers should have or be aware of before taking something on. As a result, FOSS projects lose out on not just good documentation, but good writing overall.
In this post, I'll cover what some common mistakes are, what FOSS developers have to say, examples of projects that get it right, and additional resources throughout. (Please note that this post doesn't cover how to get writers to learn code for the sake of contributing to open source; I hope to cover that at some point in the future, but this is specifically about ways developers can better identify their project's writing needs—and the people that can help them with that!)
Three Ways Of Writing For Open Source
There are many types of writing out there, and no single writer will know them all. Similarly, not all writing needs are the same in FOSS, and being able to differentiate them is a first step for both project maintainers and writers in various fields trying to understand what projects they can contribute to. While there are sometimes overlap, here are three different types of writing needs that I've seen the most in FOSS:
Copywriting/copyediting. Copywriters on FOSS projects are responsible for external communications. Copywriters have a knack for producing copy for the web, and can be called upon to help write content for a project's main website, blog posts, event announcements, social media, and emails. They may or may not have some technical experience. Copywriters do not produce technical documentation; they product content that's informative and also persuasive. In a FOSS context, they'll produce content that informs people about what a project is, what it does at a high level, how readers can find more information, and how readers can engage with the project. Copywriters and copyeditors also assist with editing grammar, fixing typos, or more substantive editing, like rewriting or rephrasing paragraphs, and making suggestions for things to add, remove, or fact check. These writers will also conduct interviews or query project maintainers/developers for more information pertaining to whatever it is they're writing about. The more information they have, the more useful the content they produce. A FOSS project that does this well is Hoodie, who has a volunteer editorial team of writers and editors that write different types of content.
UI/UX writing. UX/UI writers produce the copy that appear in a user interface. These can include error messages, labels, form field copy, button copy, headers, subheaders, and more. In companies, they generally sit with the UX team. They work with UX designers, user testers, and user researchers, and sometimes conduct research and testing on their own. They write with users in mind; they have an understanding of who their users are and what actions their users are trying to take—i.e., they help users do something. Clarity and conciseness are hallmarks of UI/UX writing. I don't have examples of people with UI/UX writing working on FOSS projects, but if your project has an interface of any kind—or perhaps produces certain messages on the command line—having a UI/UX writer on board will be helpful.
Technical writing. Technical writers—or technical communicators—write user documentation, including manpages, manuals (heh), FAQ content, how-to guides, and articles that explain certain topics or subjects in depth. These writers have an understanding of layout, writing concisely, clearly, and using only the minimum level of jargon necessary. Like UI/UX writers, technical writers want to help users do something. In FOSS, these writers should have experience working with the languages, frameworks, or other components of the project they are writing for. They will work with project maintainers/developers to best understand different use cases, and will conduct independent research and even test out instructions before getting their work reviewed by someone else. Technical writers with relevant experience can also be called upon to help write descriptive error messages. As technical editor Brian Hogan notes, the job of these writers is to advocate for the user.
How Writing Fits Into Documentation
While examples of three types of writing—copywriting, UI writing, and technical writing—are seen in FOSS, technical writing in particular is probably the most important. User documentation is a key driver for adoption, and FOSS projects understand the need behind providing useful documentation. Yet, documentation remains a major pain point in FOSS. Specifically, the lack of good documentation.
I've seen a pattern around discussing documentation in FOSS, which looks a bit like this:
- FOSS community: complains about bad documentation
- FOSS users: complains about bad documentation
- FOSS beginners: complains about bad documentation
- FOSS community: suggests FOSS beginners help by contributing to the documentation
- FOSS beginners: submits PRs correcting typos and grammar errors...but not much else
A few other folks shared similar sentiments. Taylor Barnett shares that she "wants to contribute docs PRs" but doesn't know what project maintainers are really looking for. Many projects recognize the need for better documentation but haven't been explicit about what kind of documentation they need and/or what level of experience a prospective project documentarian has with the technology, for example.
Additionally, while we tend to see FOSS newcomers as potential documentarians, they aren't necessarily equipped to produce quality documentation. They might be the types of users we consider the audience for documentation, but how much do most beginners know about producing good documentation (something different than discerning between useful and not-so-useful docs). Brian P. Hogan shares that he doesn't advocate "do[ing] FOSS by writing docs" as a general rule because he hasn't seen that work well in practice. Furthermore, Brian shares his belief that "knowing how to use the thing well is key to documenting it," something that I increasingly see to be true in my own work.
This doesn't mean all hope is lost, however. Here are a few things projects can do to attract all kinds of writers to FOSS, and build great documentation in the process:
1. Understand what kind of writing it is you're looking for. In addition to the brief summaries I provided earlier, it's important to know that documentation takes many forms. What type of documentation you need is dependent on how users will use your project. For a breakdown on different types of software documentation, refer to this blog post on documentation from Divio (a must read).
2. Create clear contribution guidelines around your project's writing needs. Once you know what types of writing you need for your project, state exactly how writers can make contributions right in the guidelines. Specify what kinds of writing you're looking for—blog writing, documentation, etc—and link out to to specific issues (or issue trackers), for example. Check our the Art of the README for helpful tips.
Speaking of issues—make it easy what issues/tasks are writing-specific. Then, break those issues down further by including the following:
What: The purpose of the project/task
Who: Who is the intended audience?
When: When will this be launched and what's the deadline?
Writing: What type of writing this is? How much experience does the writer need to have with the technology/project to participate? (You could communicate this by adding labels to issues.)
Contact: Who on the project team will serve as the main point of contact in case a writer needs to reach out to someone?
You can certainly include more than these, but the idea is to front-load all of the information a contributor will need to get it started.
3. Go where the writers are (and tell them why open source is a good fit for them). Finding writers who may—or may not—already be in the tech industry is the next, and most important, step. Here are a few places to look for amazing writers:
Write the Docs. Write the Docs is a community of software documentarians. In addition to hosting meetups and two (well attended) conferences, they also send out newsletters and have a Slack community. This is an excellent place to evangelize your project and to also understand the needs and concerns of technical writers. Help them help you!
Content Strategy and UX conferences. Of these, there are many. Content strategy conferences are an excellent place to meet both copywriters and UI/UX writers (among folks in other amazing roles). Here are a few conferences I know of:
Confab Central
Confab Intensive
Design & Content Conf
LavaCon Content Strategy Conf
IA Summit
4. Once you've found the writers, teach them Git! While technical writers and UI/UX writers might have experience with Git, offer to teach workshops on the Git workflow. If writers aren't comfortable from the command line, show them how to make changes within a GUI or submitting changes in things like Google Docs (but then adding links to those docs to issues to get them used to the project workflow).
Writers With Strong Tech Skills
There's also something to be said for writers possessing relevant tech skills before contributing to FOSS projects. Brian P. Hogan cites the technical writing and editing practice at DigitalOcean (full disclosure: I work for them) as an example: "For our team at DO, we absolutely need our writers to have dev and sysadmin skills so the writing we do is accurate and good. I'm super reluctant to write about tech I don't know. But I've seen many who aren't, and then the content is woefully inaccurate." This is certainly true of writing software documentation; you'll want to have someone with enough technical experience to write docs accurately and authoritatively.
FOSS Inspiration
Here are two open source projects that are great models for attracting writer contributors:
Webpack: Webpack's Contributing guidelines are clear, and most importantly, inclusive. They make it clear immediately that code isn't the only way to make a valid contribution, and they list out other ways people can contribute. (Documentation, copyediting, writing blog posts, and writing tutorials each get their own bullet—a great example of targetting contributors at all levels.)
Hoodie: Hoodie created an editorial team specifically for helping them with their copyediting and copywriting needs. The editorial team uses a git workflow like developer contributors, and they write blog posts, website copy, and other forms of storytelling. (I made a contribution to Hoodie last year and can attest to the team being extraordinarily helpful and welcoming.)
Conclusion
There are many different forms of writing that can benefit FOSS projects, and writers who specialize in each of them. Understanding the key differences between them will help project maintainers articulate their writing needs, and find the right kinds of people for those projects.
FOSS projects can especially benefit from working with technical writers. These writers create user documentation, and generally have a better understanding of the technologies they're documenting than people on the copywriting side. There are also different kinds of documentation, each with a specific goal in mind.
In short, finding the right people is possible. Build inroads in communities where writers congregate, and let them know all of the amazing and valid ways they can help you make your project better.
Like this post? Sign up for my Developer Content Digest newsletter for more content tips