paint-brush
How to Contribute to an Open Source Project As a Technical Writingby@ileolami
151 reads

How to Contribute to an Open Source Project As a Technical Writing

by IleolamiOctober 31st, 2024
Read on Terminal Reader
Read this story w/o Javascript
tldt arrow

Too Long; Didn't Read

This article provides a guide on how to contribute to open-source projects as a technical writer. It shares a personal experience of overcoming initial challenges and successfully making a contribution. The article outlines steps such as understanding the project, interacting with subject matter experts, identifying and fixing issues, and making a pull request. It also includes practical steps for contributing to a specific project and lists platforms that offer financial incentives for open-source contributions.
featured image - How to Contribute to an Open Source Project As a Technical Writing
Ileolami HackerNoon profile picture

Whenever I hear about a contribution to an open-source project, I always think it's a big deal. Earlier this year, I wanted to contribute to an open-source project, but I couldn't because I didn't know how to use my skills to contribute. I reached out to a senior developer for guidance, but I received a negative response.


Two months ago, while scrolling through my Discord channels, I saw a message in the Technical Writing Mentorship Program channel about contributing to an open-source project. I knew this was my chance to showcase my skills, even though I didn't know how.


I submitted my name and was added to a private channel for the project. A meeting date was set, and I joined the meeting. I asked questions about the project, and a task was assigned to me.


Within three weeks, I submitted my contribution. Revisions and corrections were made, and to my great surprise, I was the first person whose contribution was merged. The feedback was mind-blowing for a newbie in open-source projects.


Curious to know how I successfully contributed to this open-source project? This article is for you. You will learn how to contribute and make a pull request. As a bonus, you will also learn about open-source projects and platforms that pay for contributions.

Steps to Take in Contributing to an Open-Source Project

  1. Understand the project: Before you start contributing, it's important to fully understand the project.


    Research the project. This will help you know how to contribute and see if the project matches your skills and welcomes contributions to its writing aspects.


    Not all open-source projects accommodate technical writing, but some welcome both developers and technical writers.


  2. Interact with Subject Matter Experts (SME): Most projects have a Discord or Telegram channel for interaction.

    Join these channels, and introduce yourself in the introduction section, stating your intention to contribute to the project. For example:

    Good day everyone, I’m Ileolami. I’m a technical writer and frontend developer. I would like to contribute to this project as a technical writer.


    Some of the SMEs, either ambassadors or other community members, will respond and guide you. Many of these projects already provide resources in their resources section.


  3. Find the problem: This is where the work begins. After studying the documentation, you may notice problems such as grammatical errors or poor information architecture (IA).


    Some projects might be missing a feature or component, like code-based examples or graphical illustrations. You can check for these by looking at the issues raised by users.

  4. Fix the issue: Once you have identified a problem, whether it's a grammatical error, poor information architecture (IA), or a missing feature like code-based examples or graphical illustrations, it's time to provide a solution. Start by thoroughly understanding the issue and how it impacts the overall documentation or user experience.


    If it's a grammatical error, correct it, and ensure the text flows smoothly. For issues related to information architecture, reorganize the content to make it more logical and easier to navigate. If the problem is a missing feature, create the necessary code examples or illustrations and integrate them into the documentation.


  5. Editing: After making your changes, double-check for accuracy and consistency. Ensure that your solution aligns with the project's style guide and standards. Once you are confident in your work, submit a pull request with a detailed explanation of the changes you made and why they were necessary. This will help the maintainers understand your contributions and approve them more quickly.


  6. Make a pull request: Making a Pull Request (PR) involves submitting your changes to the project's repository so that they can be reviewed and potentially merged into the main codebase.


    Fill out the PR form with a clear and concise title that summarizes your changes. In the description, provide a detailed explanation of what you did, why you did it, and how it improves the documentation or codebase. Mention any specific issues you addressed, and if applicable, link to the related issue tickets.


  7. Contribution Successfully: After submitting your PR, be prepared to engage with reviewers. They may ask questions, request further changes, or provide feedback. Respond promptly and courteously to their comments, making any necessary adjustments to your PR. Once all feedback has been addressed and the reviewers are satisfied, your PR will be merged into the main codebase, and your contributions will become part of the project.

Practical Steps

Now that you know the steps for contributing to an open-source project, let's put it into practice. This time, you will contribute to the Technical Writing Mentorship Program (TWMP) project by submitting a blog post.

Prerequisite

  1. Code Editor such as Vscode
  2. Knowledge in Markdown
  3. Git and GitHub
  4. Jar of Water

Fork and Clone the Repo

  1. Go to the TWMP repo.


  2. Click on Fork to fork the repo.

  3. Choose an owner, and create a fork.

  4. Select the a Clone button from the repository.


  5. Copy the clone command (either the HTTPS or SSH format)

  6. Change to the local directory where you want to clone the repository.


  7. Paste the copied command.

    HTTPS:

    https://github.com/Technical-writing-mentorship-program/Technicalwritingcourse.git
    

    SSH:

    [email protected]:Technical-writing-mentorship-program/Technicalwritingcourse.git
    

    GitHub CLI:

    gh repo clone Technical-writing-mentorship-program/Technicalwritingcourse
    

Make Your Changes

  1. Open the cloned repository in your code editor (e.g., VSCode).


  2. Navigate to the file or section where you want to make your contribution.


  3. Create a new file under blog. Ensure your article aligns with the TWMP's style guide and standards.

Create a New Branch

  1. Open your terminal, and navigate to the cloned repository directory.


  2. Create a new branch for your changes:

     git checkout -b your-branch-name
    
  3. Verify that you are on the new branch by running:

     git branch
    
  4. Make your changes or additions in this new branch.

Commit and Push Your Changes

  1. After making your changes, open your terminal, and navigate to the cloned repository directory.


  2. Stage your changes by running:

     git add .
    
  3. Commit your changes with a meaningful message:

     git commit -m "A new article called "how to build a doc site"
    
  4. Push your changes to your forked repository:

     git push origin your-branch-name
    

Open Source Projects that Pay For Contributing

While many open-source projects rely on volunteer contributions, some offer financial incentives for contributions. Here are a few platforms and projects that pay for open-source contributions:


  1. Google Season of Docs: This program provides stipends to technical writers who work on open-source projects. Writers collaborate with open-source organizations to improve their documentation.


  2. Outreachy: Outreachy offers paid internships to work on open-source projects. It is aimed at underrepresented groups in tech, including women, trans people, and people of color.


  3. Gitcoin: Gitcoin is a platform that connects developers with open-source projects that offer bounties for completed tasks. While it primarily focuses on code contributions, some projects also seek technical writing help.


  4. Mozilla Open Source Support (MOSS): Mozilla offers grants to open-source projects that align with their mission. These grants can be used to pay contributors, including technical writers.


  5. OnlyDust: This is a platform that blockchain-based projects most especially Starknet projects and rewards every contributor.


With this guide, I hope to see you throw your hat into the ring 👍🏽.