iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Before requesting review on a documentation pull request, check the repository’s contribution rules, verify the content and its rendered output, and review the complete diff with the required validation. The exact commands and expectations depend on the project; there is no universal documentation checklist that replaces its own guidance.
1. Find and follow the repository’s instructions
Before editing or submitting, look for the project’s CONTRIBUTING.md, documentation-specific guidance, pull-request template, and any linked style or build instructions. These may be in the repository root, docs, or .github. GitHub explains where contribution instructions may live and how repositories can surface them to contributors: GitHub’s guide to contributor guidelines.
| # | Preview | Product | Price | |
|---|---|---|---|---|
| 1 |
|
The Handbook of Technical Writing with 2020 APA Update | $55.96 | Buy on Amazon |
| 2 |
|
Handbook of Technical Writing, Tenth Edition | $35.82 | Buy on Amazon |
| 3 |
|
The Handbook of Technical Writing | $44.98 | Buy on Amazon |
| 4 |
|
The Technical Writer's Handbook: Writing with Style and Clarity | $41.98 | Buy on Amazon |
| 5 |
|
The Insider's Guide to Technical Writing | $35.95 | Buy on Amazon |
Use the target repository’s directions rather than assuming that a checklist from another project applies. For example, scikit-learn’s documentation contribution guidance asks contributors to follow its documentation instructions, use its pull-request template, and check that they can build the docs locally. Its current stable documentation identifies itself as version 1.9.1; those directions are specific to that project, not a universal requirement.
Free tools Windows power users keep installed
One-click scans. No signup required.
2. Check the content, links, and rendered documentation
Review the changed text for accuracy and completeness, then verify its links and inspect how it appears to readers. A source file can look correct while the generated page has broken formatting, missing content, or other presentation problems.
#1 Best Overall
Follow the project’s workflow: build locally when instructed, or inspect a CI-generated pull-request preview when that is how the project validates documentation. Open edX, for example, automatically builds documentation for pull requests and asks contributors to check for a successful build, errors or warnings, and expected presentation. Its guidance also calls for manually verifying internal and external links, since a build may not catch a stale or inaccurate destination: Open edX documentation workflow. Scikit-learn likewise directs contributors to check the rendered documentation.
- Source review: Is the wording accurate, complete, and consistent with nearby documentation?
- Link review: Do internal and external links lead to the intended, current information?
- Rendered-output review: Does the built page or pull-request preview display as expected, with no relevant build errors or warnings?
3. Review the full diff and confirm required checks
Before requesting review, inspect the entire diff—not just the lines you intended to change—for accidental edits, unrelated formatting changes, or missing files. GitHub’s review guidance includes self-review of the diff and confirmation that relevant checks have run: GitHub’s pull-request review guidance.
Rank #2
Run the checks the repository requires and note the relevant automated and manual validation in the pull request. CNCF contributor-guide guidance recommends explaining which checks contributors should perform and how to run them locally: CNCF guidance for contributor documentation. Do not run unrelated tests just to satisfy a generic checklist; use the project’s directions and the scope of your change to decide what is relevant.
Scale validation to the change
A typo-only correction may need less validation than a new documentation page, changed code examples, or edits to the documentation build configuration. The repository’s instructions determine the required checks. A draft or early pull request can also be useful in some workflows; GitHub and Open Source Guides describe opening a pull request before work is complete when early feedback is helpful. See GitHub’s pull-request guide and the Open Source Guides contribution guide.
Quick Recap
Best Value
Rank #4
- Used Book in Good Condition
Rank #3
- Small correction: Check the changed text and links, inspect the diff, and follow any project-specific lightweight validation.
- New or substantially revised page: Check accuracy and links, build or inspect the preview, and review the complete diff.
- Examples or build-related changes: Follow the repository’s relevant example, test, and documentation-build instructions, then inspect the rendered result.
Use this preflight before requesting review:
- Rules: Have you read the repository’s contribution and documentation guidance and completed the applicable pull-request template?
- Reader experience: Have you checked the content and links, and inspected the built page or preview?
- Change and validation: Have you reviewed the full diff and confirmed the checks required for this change have run?
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
