This URL is contribute to docs: a documentation good first issue, then a small PR in docs/ (or the page the ticket named).
It is not “docs as your language-specific first PR.” Those live on the language hubs — Python Sphinx, rustdoc, godoc, DocC. Use those when the stack is the point. It is not a general non-code roundup. Use this page when the job is a named hole in the docs: a wrong example, a missing flag, a broken link.
A docs merge is a real first contribution. Maintainers close unasked rewrites. They merge the snippet that actually runs.
What counts
The issue already names the hole.
- A command in
docs/that exits 2 because a flag was renamed. - An example that imports a module that no longer exists.
- A link in the page that 404s.
- A missing argument on a documented CLI or API.
- A typo that changes meaning (wrong default, wrong env var).
That is the PR. One page, one fact, one example.
It is not:
- Rewriting Getting Started because you would have ordered the sections differently
- Restyling
docs/, swapping the theme, or “improving the voice” - A README nit nobody asked for
- Translating the whole guide
- Drive-by formatter or lint on markdown you did not need to touch
If the ticket is “docs need love,” walk. That is a wishlist. Pick a thread with a file path or a broken snippet.
Find a documentation good first issue
Look for labels like docs, documentation, good first issue and a body that points at a page. Then still run the merge checks: specified, unclaimed, recent maintainer reply. That checklist is how to pick an issue that will get merged.
Hunt on a live list, not a gist of famous READMEs:
Filter, then read the issue. “Fix docs” with no path is not small.
How to search and how labels lie: how to find good first issues.
Do not rewrite the tutorial
You are not the new docs owner.
Stay on the file the issue named. If CONTRIBUTING has a docs style guide, follow it. Do not invent a second voice. Do not expand “add the --json flag to this example” into a new Concepts chapter.
Unasked restyles review as policy. They stall. The named hole does not.
How to verify
Proof is not that you read it and it looks nicer.
- Run the project docs script if they have one, named in CONTRIBUTING.
- If there is no script, render the named page the way they already preview: GitHub markdown view, or the static HTML they ship.
- Run the example. Copy the snippet. If it is a CLI flag, run that command. If it is a link, click it.
Say in the PR which of those you did. That is how to write a pull request description. Fork and open: first pull request guide.
If you cannot boot their docs toolchain tonight, pick a ticket whose page you can still render and whose example you can still run. Do not add a new docs generator so you can iterate.
Ship the small PR
Comment once that you are taking the issue. Keep the diff on that hole. Link the ticket. Stay for review.
Do not mix a docs fix with a drive-by code change while you were there.
Related
- How to find good first issues — live hubs, then the thread.
- How to pick an issue that will get merged — specified, unclaimed, not a leftover label.
- First pull request guide — fork, branch, open the PR.
- How to write a pull request description — what changed, how you built or ran the page.
FAQ
Is a docs PR a real first contribution? Yes, if it is the hole they asked for. A merge is a merge. A rewrite of the guide is not more real; it is more likely to close.
Can I just fix typos in the README? Only if the issue named that typo (or a broken meaning). Unasked README nits get closed. Look in docs/ for the named page.
The example is wrong but the issue is improve docs. Leave it. Wait for a path, a flag, or a snippet. Or find another ticket.
Do I need to write a new tutorial? No. Add the missing flag, fix the link, make the example run. Stop.
How do I prove it? Their docs script, or the named page rendered, plus the command or link you actually ran. Paste that in the PR.
The job is: one named hole in the docs, verified, small diff. That is the whole page.