Contributing to Elixir Documentation: A Step-by-Step Guide

Introduction Elixir is a functional, concurrent, and dynamically typed language built on top of the Erlang VM. Since its release in 2012, Elixir has gained popularity due to its friendly syntax, scalability, and fault tolerance. Like many open-source projects, Elixir is hosted on GitHub and relies on community contributions to evolve. One of the most accessible ways to contribute to the project is by improving its documentation - fixing typos, enhancing explanations, or resolving formatting issues. In this article, I'll share my experience contributing to Elixir's documentation and provide a step-by-step guide for those looking to do the same. Why Contribute to Documentation? Before diving into the technical details, it's worth highlighting the importance of documentation contributions: Accessibility for beginners: Clear and accurate documentation makes the language more accessible to new developers. Entry point: It's an excellent gateway to open-source contributions, especially for newcomers. Deep learning: Reviewing and improving documentation is an effective way to deepen your own understanding of the language. Community building: It helps strengthen and expand the Elixir community. My contributions to Elixir have primarily been Markdown syntax corrections - small but important changes to enhance documentation quality. This gradual approach is ideal for getting started, with the potential to later advance to test and code contributions. Prerequisites To contribute to Elixir's documentation, you'll need: Basic knowledge of Git and GitHub Familiarity with Markdown A basic understanding of Elixir is helpful but not essential for simple documentation fixes. A text editor (such as VSCode, Neovim, etc.) Complete Guide to Contributing to Elixir - From Fork to PR Step 1: Fork the Repository Visit the Elixir repository: https://github.com/elixir-lang/elixir Click the "Fork" button in the top-right corner Wait for the fork to be created in your GitHub profile Step 2: Clone Your Fork to Your Machine # Replace 'your-username' with your GitHub username git clone https://github.com/your-username/elixir.git cd elixir Step 3: Configure the Upstream # Add the original repository as 'upstream' git remote add upstream https://github.com/elixir-lang/elixir.git # Verify the remotes are correctly configured git remote -v # Should show: # origin https://github.com/your-username/elixir.git (fetch) # origin https://github.com/your-username/elixir.git (push) # upstream https://github.com/elixir-lang/elixir.git (fetch) # upstream https://github.com/elixir-lang/elixir.git (push) Step 4: Update the Main Branch # Ensure you're on the main branch git checkout main # Elixir uses 'main' as the primary branch # Fetch updates from the original repository git fetch upstream # Merge the upstream updates with your local branch git merge upstream/main # Update your GitHub fork git push origin main Step 5: Create a Branch for Your Contribution # Create a new branch with a descriptive name git checkout -b fix-doc-markdown-links Step 6: Make the Necessary Changes This is where you actually contribute! To illustrate with an example, let's fix a Markdown link formatting issue: # Edit the file with any text editor you prefer (VSCode, Sublime, Atom, Vim, etc.) # For example, if you use Neovim: nvim lib/elixir/pages/getting-started/debugging.md # Or if you prefer VSCode: # code lib/elixir/pages/getting-started/debugging.md Change: Move commas outside the brackets in links: From: [Linux Trace Toolkit,](url) [DTRACE,](url) To: [Linux Trace Toolkit](url), [DTRACE](url), Step 7: Review Your Changes # Check which files have been modified git status # Examine the specific changes git diff Example git diff output: diff --git a/lib/elixir/pages/getting-started/debugging.md b/lib/elixir/pages/getting-started/debugging.md index e80b3febf..18b7357ae 100644 --- a/lib/elixir/pages/getting-started/debugging.md +++ b/lib/elixir/pages/getting-started/debugging.md @@ -182,7 +182,7 @@ We have just scratched the surface of what the Erlang VM has to offer, for examp * Alongside the observer application, Erlang also includes a [`:crashdump_viewer`](`:crashdump_viewer`) to view crash dumps - * Integration with OS level tracers, such as [Linux Trace Toolkit,](https://www.erlang.org/doc/apps/runtime_tools/lttng) [DTRACE,](https://www.erlang.org/doc/apps/runtime_tools/dtrace) and [SystemTap](https://www.erlang.org/doc/apps/runtime_tools/systemtap) + * Integration with OS level tracers, such as [Linux Trace Toolkit](https://www.erlang.org/doc/apps/runtime_tools/lttng), [DTRACE](https://www.erlang.org/doc/apps/runtime_tools/dtrace), and [SystemTap](https://www.erlang.org/doc/apps/runtime_tools/systemtap) * [Microstate accounting](`:msacc`) measures how

May 10, 2025 - 19:30

Contributing to Elixir Documentation: A Step-by-Step Guide

Introduction

Elixir is a functional, concurrent, and dynamically typed language built on top of the Erlang VM. Since its release in 2012, Elixir has gained popularity due to its friendly syntax, scalability, and fault tolerance.

Like many open-source projects, Elixir is hosted on GitHub and relies on community contributions to evolve. One of the most accessible ways to contribute to the project is by improving its documentation - fixing typos, enhancing explanations, or resolving formatting issues.

In this article, I'll share my experience contributing to Elixir's documentation and provide a step-by-step guide for those looking to do the same.

Why Contribute to Documentation?

Before diving into the technical details, it's worth highlighting the importance of documentation contributions:

Accessibility for beginners: Clear and accurate documentation makes the language more accessible to new developers.
Entry point: It's an excellent gateway to open-source contributions, especially for newcomers.
Deep learning: Reviewing and improving documentation is an effective way to deepen your own understanding of the language.
Community building: It helps strengthen and expand the Elixir community.

My contributions to Elixir have primarily been Markdown syntax corrections - small but important changes to enhance documentation quality. This gradual approach is ideal for getting started, with the potential to later advance to test and code contributions.

Prerequisites

To contribute to Elixir's documentation, you'll need:

Basic knowledge of Git and GitHub
Familiarity with Markdown
A basic understanding of Elixir is helpful but not essential for simple documentation fixes.
A text editor (such as VSCode, Neovim, etc.)

Complete Guide to Contributing to Elixir - From Fork to PR

Step 1: Fork the Repository

Visit the Elixir repository: https://github.com/elixir-lang/elixir
Click the "Fork" button in the top-right corner
Wait for the fork to be created in your GitHub profile

Step 2: Clone Your Fork to Your Machine

# Replace 'your-username' with your GitHub username
git clone https://github.com/your-username/elixir.git
cd elixir

Step 3: Configure the Upstream

# Add the original repository as 'upstream'
git remote add upstream https://github.com/elixir-lang/elixir.git

# Verify the remotes are correctly configured
git remote -v
# Should show:
# origin    https://github.com/your-username/elixir.git (fetch)
# origin    https://github.com/your-username/elixir.git (push)
# upstream  https://github.com/elixir-lang/elixir.git (fetch)
# upstream  https://github.com/elixir-lang/elixir.git (push)

Step 4: Update the Main Branch

# Ensure you're on the main branch
git checkout main   # Elixir uses 'main' as the primary branch

# Fetch updates from the original repository
git fetch upstream

# Merge the upstream updates with your local branch
git merge upstream/main

# Update your GitHub fork
git push origin main

Step 5: Create a Branch for Your Contribution

# Create a new branch with a descriptive name
git checkout -b fix-doc-markdown-links

Step 6: Make the Necessary Changes

This is where you actually contribute! To illustrate with an example, let's fix a Markdown link formatting issue:

# Edit the file with any text editor you prefer (VSCode, Sublime, Atom, Vim, etc.)
# For example, if you use Neovim:
nvim lib/elixir/pages/getting-started/debugging.md
# Or if you prefer VSCode:
# code lib/elixir/pages/getting-started/debugging.md

Change: Move commas outside the brackets in links:

From: [Linux Trace Toolkit,](url) [DTRACE,](url)
To: [Linux Trace Toolkit](url), [DTRACE](url),

Step 7: Review Your Changes

# Check which files have been modified
git status

# Examine the specific changes
git diff

Example git diff output:

diff --git a/lib/elixir/pages/getting-started/debugging.md b/lib/elixir/pages/getting-started/debugging.md
index e80b3febf..18b7357ae 100644
--- a/lib/elixir/pages/getting-started/debugging.md
+++ b/lib/elixir/pages/getting-started/debugging.md
@@ -182,7 +182,7 @@ We have just scratched the surface of what the Erlang VM has to offer, for examp
   * Alongside the observer application, Erlang also includes a [`:crashdump_viewer`](`:crashdump_viewer`) to view crash dumps
-  * Integration with OS level tracers, such as [Linux Trace Toolkit,](https://www.erlang.org/doc/apps/runtime_tools/lttng) [DTRACE,](https://www.erlang.org/doc/apps/runtime_tools/dtrace) and [SystemTap](https://www.erlang.org/doc/apps/runtime_tools/systemtap)
+  * Integration with OS level tracers, such as [Linux Trace Toolkit](https://www.erlang.org/doc/apps/runtime_tools/lttng), [DTRACE](https://www.erlang.org/doc/apps/runtime_tools/dtrace), and [SystemTap](https://www.erlang.org/doc/apps/runtime_tools/systemtap)
   * [Microstate accounting](`:msacc`) measures how much time the runtime spends in several low-level tasks in a short time interval

Step 8: Add and Commit Your Changes

# Add the modified file to staging
git add lib/elixir/pages/getting-started/debugging.md

# Make a commit with a descriptive message
git commit -m "Docs: Fix markdown link formatting in debugging section"

Step 9: Push Your Changes to Your Fork

# Publish the branch to your fork repository
git push origin fix-doc-markdown-links

Step 10: Create the Pull Request

Visit your fork on GitHub
You'll see a banner suggesting to create a PR from your new branch
Click "Compare & pull request"
Fill in the PR details:

PR Title:

Docs: Fix markdown link formatting in debugging guide

PR Description:

This PR fixes the markdown link formatting in the debugging documentation where commas were incorrectly placed inside the link brackets rather than outside. This small correction improves the visual consistency of links throughout the documentation and follows standard markdown best practices.

Before:
* Integration with OS level tracers, such as [Linux Trace Toolkit,](url) [DTRACE,](url) and [SystemTap](url)

After:
* Integration with OS level tracers, such as [Linux Trace Toolkit](url), [DTRACE](url), and [SystemTap](url)

Click "Create pull request"

Step 11: Respond to Feedback (if necessary)

If the maintainers request changes:

# Make the requested changes
git add [modified-files]
git commit -m "Adjustments based on PR feedback"
git push origin fix-doc-markdown-links

The PR will automatically update with your new commits.

Step 12: Cleanup After Your PR is Merged

When your PR is accepted and merged:

# Return to the main branch
git checkout main

# Update your local repo with upstream changes
git fetch upstream
git merge upstream/main

# Update your GitHub fork
git push origin main

# Delete the local branch you used
git branch -d fix-doc-markdown-links

# Delete the remote branch (optional)
git push origin --delete fix-doc-markdown-links

Additional Tips

Understanding the Documentation Structure

For more effective contributions, it's important to understand how Elixir's documentation is organized. Elixir uses a specific documentation format based on Markdown. You can learn more about this in the official documentation.

Types of Documentation Contributions

Documentation contributions can include:

Spelling and grammar corrections
Markdown formatting improvements
Clarification of code examples
Addition of more detailed examples
Translation to other languages

Progression of Contributions

As mentioned, starting with documentation is an excellent entry point. The natural progression would be:

Documentation: Simple corrections, formatting improvements
Tests: Adding or improving tests to ensure functionality
Code: Implementing new features or fixing bugs

My Personal Experience

My contributions to Elixir started simply, with corrections to the Markdown formatting in the documentation. These small contributions gave me the confidence to continue participating in the community.

The review process by the maintainers was educational and respectful, making the experience very positive. Each accepted PR, no matter how small, represents an improvement for all users of the language.

Conclusion

Contributing to open-source projects like Elixir is an enriching experience that benefits both you and the community. Documentation is an excellent entry point for those new to the open-source world.

I hope this guide has shown that the process is accessible and that you feel encouraged to make your first contribution. Remember: every contribution matters, no matter how small it may seem!

Do you have any questions about contributing to Elixir? Leave them in the comments below!