Introduction to Contributing to Documentation

Contributing to documentation projects helps improve open source and internal tools. Learn how to find projects, make your first contribution, and build a portfolio.

What You'll Learn

You will learn how to find documentation projects that need contributors, understand the workflow for making contributions, and build a portfolio through open source documentation.

Why It Matters

Open source documentation is often under-maintained. Contributing improves the project, builds your reputation, and demonstrates your skills to employers.

Real-World Use

DodaTech contributors started by fixing typos and broken links, then progressed to writing full tutorials. Many now have contributing credits on their resumes.

flowchart LR
  A[Contributing to Docs] --> B[Find Projects]
  A --> C[Make Contributions]
  A --> D[Build Portfolio]
  B --> E[Good First Issues]
  B --> F[Project Needs]
  C --> G[PR Process]
  C --> H[Review Process]
  D --> I[Contributor Profile]
  D --> J[Credits]
  E:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Why Contribute to Documentation

Benefits for Contributors

Benefits for Projects

def quantify_doc_impact(contributions):
    typo_fixes = sum(1 for c in contributions if c['type'] == 'typo')
    new_pages = sum(1 for c in contributions if c['type'] == 'new_page')
    updates = sum(1 for c in contributions if c['type'] == 'update')
    
    print(f"Typo fixes: {typo_fixes}")
    print(f"New pages: {new_pages}")
    print(f"Updates: {updates}")
    print(f"Total contributors: {len(set(c['author'] for c in contributions))}")

contribs = [
    {'type': 'typo', 'author': 'alice'},
    {'type': 'new_page', 'author': 'bob'},
    {'type': 'update', 'author': 'alice'},
    {'type': 'typo', 'author': 'charlie'},
]
quantify_doc_impact(contribs)

Expected output:

Typo fixes: 2
New pages: 1
Updates: 1
Total contributors: 3

Getting Started

Finding Projects

1. Look for "good first issue" or "help wanted" labels
2. Check the docs directory for outdated content
3. Read the contributing guide for requirements
4. Start with small fixes: typos, broken links, formatting

First Contribution Workflow

# Fork the repository
git fork https://github.com/project/docs

# Clone your fork
git clone https://github.com/your-username/docs
cd docs

# Create a branch
git checkout -b fix-typo-in-readme

# Make your change
# Commit with descriptive message
git commit -m "Fix typo in README: 'recieve' -> 'receive'"

# Push and create PR
git push origin fix-typo-in-readme

Common Mistakes

1. Starting Too Big

Do not try to rewrite the entire documentation as your first contribution. Start with small, focused fixes.

2. Not Reading the Contributing Guide

Every project has specific requirements for documentation style, format, and PR Process. Read the guide first.

3. Ignoring the Style Guide

Documentation must match the project's established style. Check for a style guide before writing.

4. No Communication

Ask before working on significant changes. The maintainers may already be updating that section.

5. Not Responding to Feedback

PR review is collaborative. Respond to feedback and update your contribution as requested.

Practice Questions

1. What is the best first contribution to documentation?

A small fix like a typo, broken link, or formatting issue. It is low risk and teaches the workflow.

2. Why should you read the contributing guide before starting?

Each project has specific requirements for style, format, and PR process. Ignoring them wastes your time and the maintainers'.

3. How does contributing to docs build your portfolio?

Public contributions demonstrate your skills to employers. Each PR is a verifiable work sample.

4. What should you do before working on a large contribution?

Communicate with the maintainers. Ask if the work is needed and agree on the approach.

5. Challenge: Find three open source projects with documentation needs. Identify one good first issue for each.

FAQ

Mini Project

Find an open source project with documentation needs. Read its contributing guide, identify a small fix (typo, broken link, or formatting), and submit a Pull Request.

What's Next

Now that you understand the basics, learn Why Contribute to Docs in more depth. Then study the Contributing Guide Template.