Good First Issues for Documentation

Good first issues are documentation tasks suitable for new contributors. Learn how to identify, label, and maintain beginner-friendly documentation issues.

What You'll Learn

You will learn what makes a good first issue, how to create them, how to label them, and how to support first-time contributors through the Process.

Why It Matters

Good first issues are the entry point for new contributors. A well-designed first issue can turn a curious Visitor into a long-term contributor.

Real-World Use

DodaTech maintains a pool of good first issues for documentation. These include typo fixes, broken link repairs, and adding missing sections to existing tutorials.

flowchart LR
  A[Good First Issues] --> B[Characteristics]
  A --> C[Types]
  A --> D[Support]
  B --> E[Small Scope]
  B --> F[Clear Instructions]
  B --> G[Quick Win]
  C --> H[Typo Fixes]
  C --> I[Broken Links]
  C --> J[Missing Sections]
  D --> K[Mentoring]
  D --> L[Quick Response]
  E:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Characteristics of a Good First Issue

def is_good_first_issue(issue):
    checks = {
        'estimated_hours': issue['estimated_hours'] <= 2,
        'has_clear_description': len(issue['description']) > 100,
        'has_instructions': 'steps' in issue or 'instructions' in issue['description'],
        'no_external_dependencies': not issue.get('needs_external_approval', False),
        'has_example': issue.get('example') is not None,
    }
    
    met = sum(1 for v in checks.values() if v)
    return met >= 4, checks

issue = {
    'estimated_hours': 1,
    'description': 'Add Common Mistakes section to the Python variables tutorial. See the Python functions tutorial for an example.',
    'example': 'content/python/functions.md',
}
is_good, details = is_good_first_issue(issue)
print(f"Is good first issue: {is_good}")

Expected output:

Is good first issue: True

Types of Good First Issues

Typo Fixes

## Issue: Fix typos in Getting Started guide

**Location**: content/getting-started.md
**Description**: Several typos in the introduction section:
- Line 12: "recieve" should be "receive"
- Line 24: "occuring" should be "occurring"
- Line 45: "seperate" should be "separate"

**Instructions**: Edit the file and fix the three typos.

Broken Link Fixes

## Issue: Fix broken link in API authentication guide

**Location**: content/api/authentication.md
**Broken link**: /api/v2/endpoints (404 error)
**Correct link**: /api/v3/endpoints

**Instructions**: Find the broken link and replace it with the correct URL.

Missing Sections

issue:
  title: "Add FAQ section to Python Loops tutorial"
  location: "content/python/loops.md"
  description: "Add 5 FAQ items about common loop questions"
  example: "See content/python/variables.md for FAQ format"
  acceptance_criteria:
    - "5 FAQ items using {{< faq >}} shortcode"
    - "Questions cover common beginner confusions"

Supporting First-Time Contributors

Before They Start

## First-Time Contributor Support

1. Clearly label the issue "good first issue"
2. Assign the issue when someone expresses interest
3. Provide exact file paths and line numbers
4. Link to relevant examples
5. Offer to answer questions

During the Process

def create_mentoring_checklist():
    return [
        "Respond to questions within 24 hours",
        "Point to examples and documentation",
        "Explain why changes are needed",
        "Be patient with Git questions",
        "Provide specific feedback on PR",
        "Celebrate the first merged PR",
        "Ask if they want another issue",
    ]

for item in create_mentoring_checklist():
    print(f"- {item}")

Expected output:

- Respond to questions within 24 hours
- Point to examples and documentation
- Explain why changes are needed
- Be patient with Git questions
- Provide specific feedback on PR
- Celebrate the first merged PR
- Ask if they want another issue

Maintaining the Pool

Keep a steady supply of good first issues.

def check_good_first_issue_pool(issues):
    active = [i for i in issues if i['status'] == 'open' and i['label'] == 'good first issue']
    print(f"Active good first issues: {len(active)}")
    
    if len(active) < 5:
        print("Need to create more good first issues")
    elif len(active) > 20:
        print("Pool is healthy")
    else:
        print("Pool is adequate")

issues = [
    {'status': 'open', 'label': 'good first issue'},
    {'status': 'open', 'label': 'good first issue'},
    {'status': 'open', 'label': 'bug'},
]
check_good_first_issue_pool(issues)

Expected output:

Active good first issues: 2
Need to create more good first issues

Common Mistakes

1. Issues That Are Too Large

A first issue that requires 10 hours of work will scare away new contributors. Keep them under 2 hours.

2. Insufficient Instructions

"Improve this page" is not helpful. Specify exactly what to change and where.

3. No Examples

Contributors learn from examples. Link to similar completed issues or existing pages.

4. Slow Response

First-time contributors who wait days for a response lose momentum. Respond quickly.

5. Not Following Up

After the first PR is merged, ask if they want another issue. Convert one-time contributors into regulars.

Practice Questions

1. What characteristics make a good first issue?

Small scope (under 2 hours), clear instructions, quick win, and no domain expertise needed.

2. What are three types of good first issues for documentation?

Typo fixes, broken link fixes, and adding missing sections.

3. Why is quick response important for first-time contributors?

Slow responses break momentum. First-time contributors who wait days may lose interest.

4. How many good first issues should a project maintain?

5-10 active issues. Too few means no entry point. Too many may indicate larger problems.

5. Challenge: Create 5 good first issues for a documentation project. Include clear descriptions, file locations, instructions, and examples.

FAQ

Mini Project

Create a pool of 5 good first issues for a documentation project. For each issue, write a clear description, specify the file location, provide step-by-step instructions, and link to an example.

What's Next

Now you are ready for the Contributing Project. Apply everything you have learned to make a meaningful contribution to a documentation project.