Pull Request Templates for Documentation

In this tutorial, you will learn about Pull Request Templates for Documentation. We cover key concepts, practical examples, and best practices to help you master this topic.

Pull request templates standardize the information contributors provide when submitting documentation changes, making reviews faster and more consistent.

What You'll Learn

You will learn how to create effective PR templates for documentation, what sections to include, and how templates improve the contribution workflow.

Why It Matters

PRs without templates lack context. Reviewers must ask basic questions about the change, slowing down the Process.

Real-World Use

DodaTech uses a PR template that asks for summary, related issues, quality checklist, screenshots, and testing steps.

flowchart LR
  A[PR Templates] --> B[Template Design]
  A --> C[Automation]
  A --> D[Enforcement]
  B --> E[Summary]
  B --> F[Checklist]
  C --> G[Labeling]
  C --> H[Auto-Review]
  D --> I[Required Fields]
  E:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

PR Template Design

Template Location

PR templates are stored in the Repository.

.github/PULL_REQUEST_TEMPLATE/
  ├── documentation.md
  ├── code.md
  └── bug-fix.md

Essential Sections

# Documentation PR Template

## Description
[Describe the documentation change and why it is needed]

## Related Issues
[Link to related issues using "Closes #123" syntax]

## Content Type
- [ ] New tutorial
- [ ] Update existing page
- [ ] Fix error or bug
- [ ] Add missing section

## Checklist
- [ ] Content follows style guide
- [ ] Code examples tested and work correctly
- [ ] First paragraph is 140-165 characters
- [ ] Includes Mermaid diagram
- [ ] Includes 5+ Common Mistakes
- [ ] Includes 3+ Practice Questions
- [ ] Includes 5+ FAQ items
- [ ] Includes Mini Project
- [ ] All links are valid
- [ ] Build passes locally

## Screenshots
[Add screenshots if the change affects visual elements]

## Additional Notes
[Any information reviewers should know]

Template Automation

Auto-Assigning Labels

# .github/labeler.yml
documentation:
  - changed-files:
      - any: ["content/**/*.md"]

tutorial:
  - changed-files:
      - any: ["content/**/tutorials/**"]

Auto-Requesting Reviewers

def auto_assign_reviewer(pr_data):
    content_types = {
        'python': 'python-team',
        'security': 'security-team',
        'general': 'docs-team',
    }
    
    for keyword, team in content_types.items():
        if keyword in pr_data['title'].lower():
            return team
    return 'docs-team'

print(auto_assign_reviewer({'title': 'Add Python variables tutorial'}))
print(auto_assign_reviewer({'title': 'Update authentication guide'}))

Expected output:

python-team
docs-team

Template Variations

Different Templates for Different Changes

## Template: Typo Fix

### Description
[Which file and what typo]

## Template: New Tutorial

### Topic
### Word Count
### Required Sections Checklist
### Related Tutorials

## Template: Broken Link Fix

### Which Links Were Broken
### What Were They Replaced With
### Testing Confirmation

Common Mistakes

1. Too Long

A template with 20 sections is overwhelming. Keep it to 5-7 essential sections.

2. Not Required

If the template is optional, contributors skip it. Enforce the template with branch protection rules.

3. One Template for Everything

Different types of documentation changes need different information. Use multiple templates.

4. No Checklist

A checklist helps contributors verify quality before submitting. Include it in every template.

5. Not Updating Templates

As the project evolves, templates need updates. Review templates quarterly.

Practice Questions

1. Where are PR templates stored in a repository?

In .github/PULL_REQUEST_TEMPLATE/ directory.

2. What information should a PR template include?

Description, related issues, content type, checklist, screenshots, and additional notes.

3. Why use different templates for different changes?

Typo fixes and new tutorials need different information. Multiple templates collect the right information for each type.

4. How do you enforce PR template usage?

Branch protection rules can require the template to be filled. GitHub checks can verify required fields.

5. Challenge: Create PR templates for three types of documentation changes: typo fix, new tutorial, and existing page update.

FAQ

Mini Project

Create PR templates for a documentation project. Design a main template, a typo fix template, and a new tutorial template. Include checklists and required fields.

What's Next

Now that you understand PR templates, learn the Review Process for Docs. Then study Recognition and Maintainers.