Contribute to Open Source Docs in 5 Steps

Want to make an impact in open source? Here's how to contribute to documentation in 5 steps:

1. Pick a project
2. Set up your computer
3. Learn the doc layout
4. Start writing
5. Share your work

Contributing to open source docs helps others use software, showcases your skills, and empowers the community. You don't need to be a coding expert - even small edits make a difference.

Here's what you'll need:

• Git basics (cloning, committing, pushing)
• GitHub account
• Text editor
• Markdown knowledge

Let's break down each step.

Start small, follow guidelines, and be open to feedback. Your contributions can have a big impact.

Related video from YouTube

What You Need to Start

Before diving in, you'll need a few key skills and tools:

Git Basics

Git is crucial for most open source projects. Here's what to know:

• Install Git (git version to check if installed)
• Learn basic commands: clone, add, commit, push
• Understand branching and merging

Common Document Formats

Most docs use simple formats. Markdown is most common:

• Plain text with simple formatting syntax
• Widely supported on GitHub and GitLab
• Learn basic syntax for headers, lists, links, code blocks

You might also see reStructuredText (reST) and AsciiDoc.

Setting Up Online Accounts

You'll need accounts on code hosting platforms:

• Create a GitHub account (most popular)
• Set up GitLab if needed (some projects use it)
• Configure Git with your account details

Always check the project's CONTRIBUTING.md file before starting.

1. Pick a Project

Finding the right project is key. Here's how to choose:

Where to Look

GitHub hosts millions of open source projects. To find one:

• Search GitHub with keywords you like
• Explore trending repos in your preferred language
• Check out "Awesome" lists for various tech

For beginners, try these platforms:

Check What Docs are Needed

Once you find an interesting project:

1. Look for CONTRIBUTING.md
2. Check issues labeled "documentation" or "good first issue"
3. Review existing docs for improvement areas

Many projects welcome doc improvements.

Start with Easy Tasks

Begin with manageable contributions:

• Fix typos or formatting
• Update outdated info
• Add examples
• Translate docs (if multilingual)

In March 2022, a new contributor fixed Firefox keyboard shortcut docs, helping thousands of users.

2. Get Your Computer Ready

Let's set up your computer:

Copy and Download the Project

Get the project files locally:

1. Fork the repo on GitHub
2. Clone your fork to your computer

Quick guide:

git clone https://github.com/your-username/project-name.git
cd project-name

Install Needed Software

You'll need some essential tools:

For advanced work, consider:

• Sphinx: Doc generator for Python projects
• MkDocs: Fast, simple static site generator
• Read the Docs: Hosting platform for docs

"Write documentation with Git and your favorite text editor. Developers and writers both love docs as code", says Read the Docs.

Check CONTRIBUTING.md for specific setup instructions.

3. Learn the Doc Layout

Understanding the existing structure is crucial:

Look at Current Docs

Examine the docs closely:

• Organization: How are topics grouped?
• Format: What file types are used?
• Content: Any gaps or outdated info?

Linkerd's "Getting Started" guide is task-oriented and quick to complete.

Follow Writing Rules

Most projects have specific guidelines:

"A great open source documentation... is clean, written with the end user in mind, well-documented, well-presented, actively-maintained." - Adrian ABABEI

When following rules:

• Use active voice and simple sentences
• Format with headings, bullets, and links
• Include visuals for complex info
• Check spelling and grammar

sbb-itb-bfaad5b

4. Start Writing

Time to make your mark:

Choose What to Work On

Pick the right task:

1. Check GitHub Issues for "Docs" or "Help Wanted" tags
2. Review existing docs for unclear or outdated areas
3. Start small to build confidence

Write Clearly

Tips for effective writing:

• Use active voice
• Keep sentences short (20 words max)
• Use headings, bullets, and tables
• Add visuals for complex concepts

"Writing is only a fraction of your contributions as a technical writer in open source." - Fabrizio Ferri-Benedetti

Focus on the "Getting Started" section - it gets the most traffic. Make it clear and easy to follow.

Write for newcomers. Ask: "Would a beginner understand this?" If not, simplify or add context.

Check for spelling and grammar errors.

5. Share Your Work

Time to submit your changes:

Submit Your Changes

To propose your edits:

1. Push changes to your fork
2. Open a pull request (PR) on the original repo
3. Add a clear title and description

Tips for PRs:

• One PR per change or related set
• Use a short, descriptive title
• Explain why the change was needed
• Include "fixes #[issue number]" if applicable

Astro docs have an "Edit this page" link for easy contributions.

Handle Feedback

After submitting:

1. Be patient - maintainers are often volunteers
2. Stay engaged - watch for comments
3. Make requested changes promptly
4. Respond to all feedback

To update based on feedback:

1. Edit the same branch locally
2. Commit and push updates to your fork
3. The PR will auto-update

Multiple feedback rounds are normal. Stay positive and learn from it.

Tips for Good Documentation

Key practices for effective docs:

Keep It Simple

Clarity is key:

• Use plain language, avoid jargon
• Write short, direct sentences
• Break complex ideas into chunks

"If you can't explain it simply, you don't understand it well enough." - Albert Einstein

Use Good Layout

Organize for easy reading:

• Use headers and subheaders
• Use bullet points and numbered lists
• Include a table of contents for long docs

Python docs are known for clear structure.

Make Docs for Everyone

Ensure accessibility:

• Write for beginners
• Define technical terms
• Include examples and code snippets

"Say what you mean, simply and directly." - Brian Kernighan

Test your docs by following your own steps.

Common Problems and Fixes

Addressing common documentation issues:

Fixing Old Information

To tackle outdated docs:

1. Regular audits
2. Version control with Git
3. Encourage user feedback

Working with Others

Navigate collaboration:

• Clear communication in project channels
• Follow contribution guidelines
• Be patient with maintainers

"Spend time in the community to understand their work style and decision-makers."

Keeping Docs Consistent

Maintain uniform style:

1. Create and follow a style guide
2. Provide templates
3. Implement peer review

For merge conflicts:

1. Get latest changes with git pull -r upstream master
2. Identify conflicts with git status
3. Edit conflicting files
4. Add resolved files with git add
5. Commit with clear message
6. Push updates

Conclusion

Contributing to open source docs benefits you and the tech community. Your contributions matter, even small changes make a difference.

Recap:

Keep contributing to:

• Improve your writing skills
• Learn from others
• Build your reputation
• Make software more accessible

Your doc contributions are as important as code. They bridge the gap between complex software and users.

Take that next step. Find a project, dive in, and make a difference.

More Help and Tools

Resources to help your open source journey:

Learning Resources

• Git Basics: 36-minute video series on essential Git
• GitHub Learning Lab: Interactive Git and GitHub lessons
• Open Source Guide: Comprehensive resource for contributors

Finding Projects

Platforms to discover projects needing help:

Documentation Tools

Streamline your process:

• Read the Docs: Free hosting for open-source docs
• Docusaurus: Free, open-source static site generator
• GitBook: Free docs software with version control

Community Support

Join open source communities on Discord or Slack for guidance and feedback.

Always check a project's contributing guidelines before starting.

Related posts

• Open Source Web Development Projects for Beginners: A Guide
• How to Contribute to Open Source GitHub Repositories
• How to Start Contributing to Open Source Projects: A Primer
• How to Start Contributing to Open Source Projects