Alyssa Rock
Technical Writer
Alyssa Rock
Technical Writer

Blog Post

Getting started in open source as a new tech writer

December 13, 2020 open source

I’m writing this post because I’m starting to turn into a broken record on /r/technicalwriting by constantly telling new tech writers who want to break into the field about the great opportunities available in open source. Since I feel like I post the same basic reply every time, I’m going to write it a more in-depth version here and just link to it in the future.

The basic pathway to getting a job

Before I talk specifically about why you should consider contributing to open source, let’s spend just a moment talking about the general principles behind getting a job.

One of the gold standards for new job-seekers is the book What Color is Your Parachute. It walks through some of the basics of getting your first job. As a bonus, it will help you do some important soul-searching about your future profession along the way.

One thing that’s useful about this book is that it debunks some of the common myths about how to get a job. For example, it includes this image, entitled The Way a Typical Employer Prefers to Fill a Vacancy:

I want to draw your attention items #2 and #3 in this image. According to this chart, the top 2 and 3 ways that employers find candidates are by:

  • Using Proof: Hiring an unknown job hunter who brings proof of what he or she can do, with regards to the skills needed.
  • Using Best Friend or Business Colleague: Hiring someone whose work a trusted friend of yours has seen (perhaps they worked with him or her).

In other words, you’ll likely get your first job by showing a prospective employer that you have work experience and/or by making connections to that employer through your social network.

I can attest this pattern has been true for me throughout my career. For example, I’ve found most of my future workplaces primarily through my social network. 4 out of the 5 jobs that I’ve gotten over the course of my career have been because I knew someone who worked there who could personally vouch for me in some way, even if through very loose connections. Once my social network helps me get in the door for an interview, that’s when I usually need to demonstrate my qualifications using my portfolio of work and my prior work experience. My work history and writing samples usually get me the rest of the way to a final job offer.

Open source gives you work experience and builds your social network

Contributing to open source software projects gives you a path to finding a job through both source #2 (work experience) and source #3 (your social network).

Let me start by explaining how open source communities can give you some quality work experience. By their very nature, open source projects are open to contributions from anyone. No interviews are needed. All you need to do is show up regularly, roll up your sleeves, and get to work on your first contribution. As a nice side benefit, you don’t have to show up during traditional work hours. You can contribute whenever you personally have the time to do so, which means open source work can flexibly accommodate most working schedules. Over time, you’ll develop some genuine work experience that you can use to demonstrate your skills and work ethic to a potential employer.

But the true value of open source is how it will help you build your social network. If you’re a long-term, active contributor who does high quality work, people working on that project will take note. If you have a strong work ethic (meaning that you’re friendly, professional, and you follow through on your commitments), soon the other open source project contributors will notice. As you work with the community to accomplish meaningful goals, you will naturally begin to make important professional friendships and build trust with other professionals.

Some of the relationships you build in the open source community will begin to bear fruit over time. A lot of people working in open source make their contributions on the side in addition to their day jobs. And, of course, there are some people for whom the open source project is their day job. The next time one of your fellow contributors hears about an opening for a technical writer at their workplace, they will think of you. They will likely mention any job opportunities they think you would be a good fit for and might even give you a recommendation when you apply. In job-hunting terms, that’s the strongest kind of lead you can get.

I’ve seen this happen in my personal work in open source. In my (day job) at the open source project Salt, we’ve directly hired members from our active contributor community before. And after about six months of contributing to the Good Docs project, my fellow contributors started sending me job recommendations and encouraging me to apply—even in this current climate where technical writing jobs are hard to find.

You can make a meaningful contribution

The good news is that you are definitely needed if you want to make a technical writing contribution in open source. Most open source software projects have a tremendous need for technical writers. For whatever reason, open source projects attract more developers than technical writers.

As a result, most documentation is written by developers themselves. While many developers are good communicators and writers, writing is not always their primary interest and they may not have any specialized training in it, such as in information architecture.

For that reason, the contributions of any kind of technical writer are warmly welcomed in open source, no matter their experience level. Simply being enthusiastic and willing to help can go a long way. They will gladly hand over documentation tasks to you if it means they can free up more time for code.

Some caveats

Before I talk about how to get involved with open source, I do want to mention some quick caveats.

My first caveat is about college degrees. It’s certainly true that starting in open source can give you an alternative path to getting a job if you don’t have a college degree. However, open source experience is not necessarily a replacement for a college degree. Having a degree is still important since many jobs treat a degree as a minimum requirement to get an interview. And, hey, it’s worth mentioning that a college degree will prepare you with valuable critical thinking skills, plus a broadened view of the humanities and sciences. But if you’re a new graduate with no work experience or if you want to take an alternative path to getting a good job without a degree, open source can make a big difference.

Second, I want to acknowledge that there are still inequities in open source. Unfortunately, only 3% of open source contributors come from underrepresented minority groups and/or are women (see GitHub 2017 Open Source Survey). Part of the reason this depressing participation gap exists is because contributing to an open source project requires you to have some free time to spend. Unfortunately, not everyone has that luxury. If you’re working multiple jobs and/or trying to support a family on a low income, having little free time would make it quite difficult to contribute to an open source project. I don’t have a good solution to the problem of having little free time, but if you’d like to watch a thought-provoking and inspiring talk about how good documentation can help close the gap, watch Documentation for Good: Knowledge as a tool for equity and inclusion from Write the Docs Portland 2019.

Choosing the right project

Before jumping into your first project, take some time to think about your career goals, your personal strengths, and your interests. Are there specific programming languages you are interested in learning or have some prior experience with, such as Python, Javascript, or Ruby? Are there certain industries you are interested in, such as network engineering, security, health care, finance, geospace, etc.? Let those interests guide you as you explore different open source projects.

Next, ask anyone you know in the field for some interesting open source projects they would recommend. You could also possibly browse some GitHub projects or do some Google searches.

Once you’ve found a few interesting projects, lurk in their community as an observer for a little while to see if the community is a good fit for you. Read their community docs and join any communication channels (Slack, mailing lists) to begin interacting with the project contributors. Pay atention to whether the project feels welcoming and healthy. If possible, read a little bit about the project’s reputation outside of GitHub to see if there are any red flags you should be aware of.

Some communities I recommend for new technical writers:

If you really want to dive into the deep end, you could also come join me at the Salt docs, but be aware that Salt requires some deep technical knowledge to learn more about it. However, like most open source projects, we’re hungry for tech writers and would gladly mentor you!

Preparing yourself for your first contribution

After you’ve found a community that interests you, your next step will be to learn about that community’s culture. Every open source community has its own rules of etiquette and you need to spend some time learning their rules and customs around making contributions. Spend some time listening to their conversations before you jump in with your first contribution and reading their community docs, such as:

  • README
  • Contributing Guide
  • Code of Conduct
  • Any other docs they link to about community governance and administration

Then, read through some of the issues on their project board and see if any of them sound interesting. See if there’s any face-to-face working groups or meetings that you can join. That will give you a chance to talk directly with the project maintainers and active contributors so that you can get some early guidance about how to get started.

At the same time, keep in mind that you don’t really need anyone’s permission to start contributing. Once you find a way to make a meaningful contribution that interests you, just go for it. Do your best, but don’t worry too much about making mistakes. Be prepared to take criticism and feedback as a way to grow your skills. The important thing is to keep trying and learning as you go.

A word about tools

You’re probably going to need a text editor to get started. (I’m partial to Atom, but there’s many other free text editors out there.) You might also want to learn the basics of how to write documentation in Markdown.

When you’re ready to make your first contribution, it will be time to learn about Git version control. Git, GitHub, and GitLab are widely used tools in open source and they are a fundamental toolchain for anyone who wants to contribute regularly. Fortunately, that means there are a lot of resources out there to help you learn about them. A few I recommend:

  • Perhaps start by watch my video Git for the True Beginner that I made for our Open Salt Docs Clinic.
  • I recently attended an interesting presentation about how to use GitHub without interacting with the command line at all. Watch GitHub: No CLI Required.
  • I’ve heard many technical writers give praise for the free online book Learn Git in a Month of Lunches.
  • I really enjoy this interactive Javascript tutorial Learn Git Branching. (By the way, this is an open source project that you can contribute to!)

The good news is that you’ll likely use many of these tools in your first technical writing job anyway, so you might as well learn them now.

In conclusion, I wish you luck and I look forward to seeing all the great open source contributions you’re going to make!

Tags: