PR Process for Documentation — Complete Guide

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

The Pull Request process for documentation involves creating, reviewing, and merging changes. Learn the workflow from fork to merge for documentation PRs.

What You'll Learn

You will learn the complete PR workflow for documentation, how to write good PR descriptions, how to participate in reviews, and how to handle feedback.

Why It Matters

The PR process is how contributions become real. Understanding the workflow prevents common mistakes and makes the process smooth for everyone.

Real-World Use

DodaTech uses the standard GitHub PR workflow. Contributors fork the Repository, create branches, submit PRs, respond to reviews, and maintainers merge.

flowchart LR
  A[PR Process] --> B[Create Branch]
  A --> C[Make Changes]
  A --> D[Submit PR]
  A --> E[Review]
  A --> F[Merge]
  B --> G[Fork Repo]
  B --> H[Branch from Main]
  D --> I[Write Description]
  D --> J[Add Labels]
  E --> K[Address Feedback]
  E --> L[Update PR]
  F --> M[Squash Merge]
  F --> N[Delete Branch]
  G:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Step-by-Step PR Workflow

Step 1: Fork and Clone

# Fork on GitHub, then clone
git clone https://github.com/YOUR-USERNAME/project-docs
cd project-docs

# Add upstream remote
git remote add upstream https://github.com/original/project-docs

# Create a branch
git checkout -b add-authentication-tutorial

Step 2: Make Changes

Write the documentation following the style guide.

## Change Checklist

- [ ] Follows style guide
- [ ] Includes code examples
- [ ] Adds common mistakes section
- [ ] Includes practice questions
- [ ] Adds FAQ
- [ ] Builds without errors

Step 3: Commit

git add content/security/authentication.md
git commit -m "Add authentication tutorial with code examples"
git push origin add-authentication-tutorial

Step 4: Create PR

Write a clear PR description.

## PR Description Template

### Summary
Add a tutorial on API authentication covering API keys, OAuth,
and JWT with code examples for Python and JavaScript.

### Related Issues
Closes #123

### Changes
- New file: content/security/authentication.md
- Updated sidebar navigation

### Checklist
- [ ] Content follows style guide
- [ ] Code examples tested
- [ ] Build passes locally
- [ ] Links are valid

### Screenshots
N/A

Step 5: Review

def review_doc_pr(changes):
    feedback = []
    for file, content in changes.items():
        if len(content) < 500:
            feedback.append(f"{file}: Content is too short (minimum 1200 words for tutorials)")
        if '## Common Mistakes' not in content:
            feedback.append(f"{file}: Missing Common Mistakes section")
        if '## FAQ' not in content:
            feedback.append(f"{file}: Missing FAQ section")
    return feedback

changes = {
    'authentication.md': '# API Auth\n\nShort content...'
}
for f in review_doc_pr(changes):
    print(f)

Expected output:

authentication.md: Content is too short (minimum 1200 words for tutorials)
authentication.md: Missing Common Mistakes section
authentication.md: Missing FAQ section

Step 6: Merge

Once approved, a maintainer merges the PR.

PR Best Practices

Common Mistakes

1. Large PRs

A PR with 2000 lines of changes across 10 files is hard to review. Break it into smaller PRs.

2. No Description

A PR without a description forces reviewers to guess what the change does and why.

3. Ignoring Feedback

Not responding to reviewer comments or making requested changes delays the merge.

4. Forgetting to Sync

Starting from an outdated main branch creates merge conflicts. Sync your fork before creating a branch.

5. Force Pushing After Review

Force pushing after a review loses the reviewer's comments on specific lines. Use additional commits.

Practice Questions

1. What are the steps in the PR workflow for documentation?

Fork, clone, branch, make changes, commit, push, create PR, review, merge.

2. Why should PRs be kept small?

Small PRs are easier to review, have fewer merge conflicts, and are less likely to be rejected.

3. What information should a PR description include?

Summary of changes, related issues, checklist of quality items, and screenshots if applicable.

4. Why should you not force push after a review?

Force pushing rewrites history and loses the context of reviewer comments on specific lines.

5. Challenge: Simulate the PR process. Create a branch, make a documentation change, write a PR description, and describe how you would respond to 3 pieces of reviewer feedback.

FAQ

{{< faq "What if my PR is not reviewed?" >> Politely ask for review after a week. If still no response, consider contributing to a more active project. {{< /faq >}}

Mini Project

Create a PR for a documentation change in an open source project. Follow the complete workflow: fork, branch, make changes, commit, push, write a PR description, and respond to reviewer feedback.

What's Next

Now that you understand the PR process, learn Style Guide Adherence. Then study Code of Conduct.