Make Your First Documentation PR

Turn an open-source documentation issue into a review-ready GitHub pull request.

Introduction

30 Second Summary

Useful ideas often surface in community conversations before anyone turns them into work. Without clear scope, those ideas can stay buried in a long thread.

In this project, you will turn a live open-source documentation issue into a review-ready pull request on GitHub. You will add a concise process that helps maintainers convert useful content from GitHub Discussions into scoped work.

What You'll Build

You will open your public pull request and see two focused Markdown changes ready for a maintainer to review alongside your local test evidence.

By the end of this project, you'll have:

  • A repeatable discussion-to-issue process that tells maintainers what to carry from a useful Discussion into a focused issue.
  • A ready-issue checklist covering context, scope, acceptance criteria, verification, needs triage, and the matching skill: ... label.
  • A public pull request whose review page shows the two requested Markdown files, local test evidence, and Closes #113.
  • Secret Mission: Add a compact worked conversion example to docs/MAINTAINER_PLAYBOOK.md through a second commit on the same pull request.

Are there any prerequisites?

You need a GitHub account plus GitHub Desktop and Visual Studio Code on Windows.

The project includes Node.js setup if your computer does not already have version v24.20.0 LTS.

Before We Start

A focused contribution starts with a clear purpose. This is your moment to commit to documentation guidance that helps maintainers turn useful GitHub Discussions into ready, scoped issues.

Set Up the Contribution Workspace

Your contribution soon moves from GitHub Desktop into Visual Studio Code. A reliable local workflow prevents account, editor, or runtime problems from interrupting the contribution after you start editing.

This step checks the workspace foundations before any repository is cloned. No repository changes happen here.

In this step, get ready to:
  • Confirm the correct GitHub account in GitHub Desktop.
  • Set Visual Studio Code as the external editor.
  • Verify Node.js plus npm in Windows PowerShell.
Confirm your GitHub account

GitHub Desktop uses your authenticated account when it creates public contribution activity. Confirming the account now keeps your future branch and pull request attached to the correct identity.

  • Click File in the GitHub Desktop menu bar.
  • Select Options.
  • Select Accounts in the Options window.
  • Check the displayed account name against the GitHub account you want to use for issue #113.

✔️ The correct account is connected

Your GitHub account is connected to GitHub Desktop. That account now represents you throughout this public contribution.

ⓧ I need to sign in

This is the credential step in the workspace setup. The browser flow lets you confirm which account you are authorizing.

  • Click Sign Into in the Accounts panel.
  • Click Continue With Browser.
  • Complete the browser sign-in with the GitHub account you want to use for issue #113.
  • Return to GitHub Desktop.
  • Confirm the Accounts panel shows the correct GitHub account.

Your contribution identity is now connected. GitHub Desktop can use it when you publish work later.

Select Visual Studio Code as the external editor

An external editor setting tells GitHub Desktop where to send a repository when you start writing. Selecting Visual Studio Code keeps the handoff predictable.

  • Click File in the GitHub Desktop menu bar.
  • Select Options.
  • Select Integrations.
  • Select Visual Studio Code under External Editor.
  • Click Save.

The editor preference is now stored in GitHub Desktop.

  • Click File again.
  • Select Options.
  • Select Integrations.

You'll see Visual Studio Code selected under External Editor. That confirms GitHub Desktop knows which editor to use.

Verify Node.js and npm

Node.js runs the repository's validation scripts. The npm command manages the packages those scripts need.

  • Press the Windows key to open Windows search.

You'll see the Windows search field ready for an app name.

  • Type Windows PowerShell into the search field.
  • Press Enter.

You'll see a Windows PowerShell window with a command prompt.

Before you run the checks, do you expect both tools to be ready?

  • Verify both tools by running these commands:
node --version
npm --version

What do these commands confirm?

  • The first command reports the installed Node.js runtime version.
  • The second command reports the npm version included with the Node.js installation.

✔️ I see v24.20.0 and an npm version

The first line shows v24.20.0. The second line shows an npm version.

That's the workspace check complete. Node.js plus npm are ready for the repository validation commands later.

ⓧ I see an older version

An older Node.js runtime can behave differently when the repository runs its checks. Install v24.20.0 LTS to match this project.

  • Open the official Node.js download page.
  • Install Node.js v24.20.0 LTS for Windows from that page.
  • Close the current Windows PowerShell window after the installation finishes.
  • Press the Windows key to open Windows search.
  • Type Windows PowerShell into the search field.
  • Press Enter.

Before you check again, do you expect the fresh PowerShell window to report the updated runtime?

  • Verify the upgraded runtime by running these commands:
node --version
npm --version

What does the fresh check prove?

A new PowerShell window reads the updated command locations from your Node.js installation. The two outputs confirm that the runtime plus its package manager are available.

You'll see v24.20.0 on the first line. You'll see an npm version on the second line.

ⓧ Command not found

The missing command means Node.js is not available in this PowerShell session. The official Node.js installer also includes npm.

  • Open the official Node.js download page.
  • Install Node.js v24.20.0 LTS for Windows from that page.
  • Close the current Windows PowerShell window after the installation finishes.
  • Press the Windows key to open Windows search.
  • Type Windows PowerShell into the search field.
  • Press Enter.

Before you check again, do you expect the fresh PowerShell window to find both commands?

  • Verify the new installation by running these commands:
node --version
npm --version

What does the new check prove?

The first output proves Windows PowerShell can find the Node.js runtime. The second output proves npm was installed with it.

You'll see v24.20.0 on the first line. You'll see an npm version on the second line.

Still missing a version?

  • Close every Windows PowerShell window after installing Node.js. A fresh window picks up the updated command locations.
  • Confirm that you installed v24.20.0 LTS for Windows from the official Node.js download page.
  • Ask for help with the version check: Help me verify Node.js and npm in Windows PowerShell.

Your contribution workspace is ready. Next, you'll claim issue #113 and create the branch for your documentation work.

Claim the Issue and Create Your Branch

A working contribution setup now sits behind you. The next move turns your written intent into visible work on GitHub.

An upstream repository is the maintainer-owned source. A topic branch gives your documentation change a focused lane.

GitHub Desktop can create both locally. Publishing the branch reveals whether your account can write to the parent repository.

In this step, get ready to:
  • Claim issue #113 with a public comment.
  • Clone the upstream repository to your Windows computer.
  • Create a local documentation branch and reach the publishing permission prompt.
Claim issue #113 before editing

Issue claiming tells maintainers that someone is working on a task. It also helps contributors avoid making the same change at the same time.

  • Visit Open Source Starter Lab issue #113 to confirm it remains open.
  • Check the assignment area to confirm nobody is assigned.
  • Paste I would like to work on this. Please assign me. I will keep the PR focused and run npm run check before opening it. into the comment field.
  • Submit the comment.

That's your first public contribution signal. Issue #113 now shows your commitment to a focused change with a local check before submission.

Is the issue no longer available?

If the issue is closed or assigned when you arrive, another contributor now owns this task. Avoid creating duplicate work.

  • Use the linked Discussion #44 to find a contribution path that does not duplicate the claimed issue.

Help me choose a non-duplicating contribution path.

Clone the upstream repository

A clone gives you a local copy of the repository without changing the maintainer-owned version. This copy becomes the workspace for your documentation branch.

  • Return to GitHub Desktop from earlier.
  • Click File in the top menu.
  • Select Clone Repository.
  • Choose the URL tab.
  • Paste https://github.com/P-r-e-m-i-u-m/open-source-starter-lab into the repository address field.
  • Choose your preferred Windows folder under Local Path.
  • Record the selected location here: your selected Windows clone path.
  • Click Clone.

That's the repository copied locally. GitHub Desktop now shows open-source-starter-lab with main under Current Branch.

Did the repository fail to clone?

  • Confirm the repository address exactly matches https://github.com/P-r-e-m-i-u-m/open-source-starter-lab.
  • Choose a local Windows path where your account can create files.
  • Help me troubleshoot this clone.
Create the topic branch

The documentation change needs its own branch so the repository's main history stays untouched. The branch name also tells maintainers what your pull request covers.

  • Click Current Branch in GitHub Desktop.
  • Select main from the branch list.
  • Click Current Branch again.
  • Click New Branch.
  • Enter docs/discussion-to-issue-guide as the branch name.
  • Click Create Branch.

You should see docs/discussion-to-issue-guide under Current Branch. This confirms the branch exists locally from main.

Before you publish, do you think your account can write this branch directly to the parent repository?

  • Click Publish branch in GitHub Desktop.

You'll see How are you planning to use this fork? instead of a completed publication. You've reached the intended permission boundary.

Why did the fork prompt appear?

The parent repository does not grant your account write access. GitHub Desktop needs a writable copy before it can publish your branch.

A fork is a personal repository copy that stays connected to the parent project. The next step creates that copy through the prompt now on your screen.

  • Leave the fork prompt open without selecting an option.

Did the fork prompt not appear?

  • Confirm Current Branch shows docs/discussion-to-issue-guide.
  • Confirm GitHub Desktop is showing the cloned open-source-starter-lab repository.
  • Help me reach the fork prompt.

Your issue is claimed. The upstream clone now has a focused branch waiting at the permission boundary. Next, you'll use that boundary to publish through a contribution fork.

Create Your Fork and Validate the Baseline

You claimed issue #113 and reached the publishing boundary in GitHub Desktop. That prompt proves the upstream repository does not accept branch publication from your account.

A fork gives your account a writable copy while preserving its connection to the parent repository.

You will publish your topic branch through that fork. A baseline check will measure the health of the untouched repository before you edit it.

In this step, get ready to:
  • Create a fork configured for contributing to the parent project.
  • Review the two target Markdown files in Visual Studio Code.
  • Establish the repository baseline with its dependencies installed.
Create the contribution fork

The waiting prompt asks GitHub Desktop how this fork should behave. The contribution option keeps the parent repository as the destination for your future pull request.

  • Select To contribute to the parent project in the fork prompt.
  • Click Continue.

GitHub Desktop creates the fork under your account. You should see docs/discussion-to-issue-guide under Current Branch after publication completes.

That permission boundary is cleared: your branch now has a writable remote.

Why Keep the Parent Connection?

Your fork owns the published branch under your account.

The parent connection tells GitHub Desktop that future changes belong in P-r-e-m-i-u-m/open-source-starter-lab for review.

Review the target documentation

The existing documentation establishes the repository's tone and structure. Reviewing both target files helps you keep the upcoming change focused.

  • Click Repository in GitHub Desktop's top menu.
  • Click Open in default editor.
  • Expand docs in the Visual Studio Code Explorer sidebar.
  • Open docs/WEEKLY_HELP_THREAD.md from the Explorer sidebar.
  • Open docs/MAINTAINER_PLAYBOOK.md from the Explorer sidebar.

Visual Studio Code opens the local clone on docs/discussion-to-issue-guide. You should see both unchanged files in separate editor tabs.

Install dependencies and validate the baseline

A pre-edit local validation separates existing repository problems from problems introduced by your change. This check gives every later test a comparison point.

The first dependency install often takes a few minutes while npm downloads packages. A short quiet stretch is normal.

  • Click Terminal in Visual Studio Code's top menu.
  • Click New Terminal.
  • Select PowerShell from the terminal dropdown if another shell opens.
  • Install the repository dependencies by running this command:
npm install

What Does This Command Do?

The npm install command downloads the repository's dependencies into node_modules.

Those packages power the repository validation command you run next.

  • Wait for the installation to return to the PowerShell prompt.
  • Confirm node_modules appears in the Visual Studio Code Explorer sidebar.

Dependency Installation Stopped?

  • Confirm the terminal prompt points to your local clone of open-source-starter-lab.
  • Reconnect to the internet if package downloads stopped.
  • Help me diagnose the dependency installation.

Before you run the baseline check, do you expect the untouched branch to pass?

  • Validate the untouched repository by running this command:
npm run check

What Does This Command Prove?

The npm run check command runs the repository's required checks against your current branch.

Running it before any documentation edits records a clean comparison point for your contribution.

You should see the check finish successfully before the PowerShell prompt returns.

You've secured the safety line for your contribution: later test results can now be compared with this successful baseline.

Baseline Check Failed?

  • Stop after a pre-edit failure.
  • Read the first reported file or task to identify the existing problem.
  • Help me investigate the failed baseline check.

Your fork is connected to the parent project. Your published branch also starts from a verified baseline. Next up, you will turn the issue requirements into focused guidance across the two Markdown files.

Write and Validate the Documentation

Your fork now has a published documentation branch. The repository check passes before any edits.

Issue #113 needs a short bridge from an informal conversation to a scoped issue. This step turns that request into guidance that another contributor can follow.

In this step, get ready to:
  • Write concise Discussion handoff guidance for maintainers.
  • Build a ready-issue checklist for maintainers.
  • Validate the finished documentation.
Write the Discussion handoff guide

A GitHub Discussion can surface a useful request without giving a contributor enough boundaries. A concise Markdown section preserves the details needed to turn that request into workable issue.

What should the handoff capture?

  • The source link keeps the original conversation available for reference.
  • The problem or request states what needs attention.
  • Relevant context gives the request enough background.
  • The desired outcome defines what success looks like.
  • Evidence or examples preserve useful details from the conversation.
  • Switch back to docs/WEEKLY_HELP_THREAD.md in Visual Studio Code.
  • Write a concise Discussion-to-issue section near What Contributors Comment that follows the five handoff details above.
  • Save docs/WEEKLY_HELP_THREAD.md.
  • Press Ctrl+Shift+V to open its Markdown preview.

You'll see the new heading render as structured documentation. Its handoff details should be easy to scan.

Preview showing the wrong file?

  • Select the docs/WEEKLY_HELP_THREAD.md editor tab before pressing the preview shortcut again.
  • Save the file if the preview does not include your latest text.
  • Check the heading syntax if the section title renders as body text.
  • Help me fix my Markdown preview.
Add the ready-issue checklist

A ready-issue checklist defines when a request has enough detail for a contributor to begin. It gives maintainers a repeatable quality check.

What makes an issue ready?

  • Context explains why the issue matters.
  • A focused goal defines one achievable outcome.
  • Suggested files point contributors toward the likely change locations.
  • Acceptance criteria describe the required result.
  • Verification explains how contributors prove the work is complete.
  • The needs triage label marks the issue for maintainer review.
  • A relevant skill: ... label identifies the contribution skill.
  • The skill: docs label matches this documentation change.
  • Switch back to docs/MAINTAINER_PLAYBOOK.md in Visual Studio Code.
  • Write a compact ready-issue checklist near Write Issues That People Can Finish that includes every requirement above.
  • Save docs/MAINTAINER_PLAYBOOK.md.
  • Press Ctrl+Shift+V to open its Markdown preview.

You'll see the new section render with a clear heading. Each ready-issue requirement should appear as a distinct checklist item.

Checklist not rendering correctly?

  • Select the docs/MAINTAINER_PLAYBOOK.md editor tab before opening the preview again.
  • Check the Markdown list formatting if the checklist appears as plain text.
  • Confirm the exact labels appear inside the rendered checklist.
  • Help me fix this ready-issue checklist.
Validate the finished guidance

The previews confirm that readers can scan both sections. The repository check confirms that the edits follow the project's local validation rules.

  • Return to issue #113 in GitHub.
  • Confirm docs/WEEKLY_HELP_THREAD.md explains what information must move from a Discussion.
  • Confirm docs/MAINTAINER_PLAYBOOK.md includes a ready-issue checklist.
  • Confirm the checklist uses needs triage.
  • Confirm the checklist uses a relevant skill: ... label.
  • Confirm both sections stay short.

Before you run the check, do you expect both edited files to pass the same validation as the untouched baseline?

  • Validate both documentation changes by running this command in the Visual Studio Code PowerShell terminal:
npm run check

What does this command check?

The command runs the repository's validation script against your current branch. It checks your edited files through the project's established local workflow.

You'll see the command complete successfully.

You have cleared the key checkpoint: your two-file contribution passes the repository's own check.

Check command failing?

  • Save both Markdown files before rerunning the command.
  • Confirm the terminal is still using your local clone of open-source-starter-lab.
  • Read the first reported failure to identify which file needs attention.
  • Help me diagnose the failed repository check.

✔️ My documentation is ready

Both changed Markdown files now match issue #113. Their previews render correctly through the repository check.

ⓧ I'd like to double check my changes

Compare your finished documentation with this checklist before moving on.

  • Confirm docs/WEEKLY_HELP_THREAD.md covers the source link.
  • Confirm the same section covers the problem or request.
  • Confirm the same section covers relevant context.
  • Confirm the same section covers the desired outcome.
  • Confirm the same section covers evidence or examples.
  • Confirm docs/MAINTAINER_PLAYBOOK.md covers context.
  • Confirm the checklist covers a focused goal.
  • Confirm the checklist covers suggested files.
  • Confirm the checklist covers acceptance criteria.
  • Confirm the checklist covers verification.
  • Confirm the checklist includes needs triage.
  • Confirm the checklist includes a relevant skill: ... label.
  • Confirm both Markdown previews render correctly.
  • Confirm the post-edit repository check completes successfully.

Both changed Markdown files now form a focused contribution. Next up, you'll package the verified diff into a commit for maintainer review.

Commit and Open the Pull Request

Your two Markdown guides now meet the acceptance criteria for issue #113. The next goal is to package that work into a focused pull request for maintainer review.

A maintainer should be able to verify your contribution without reconstructing your intent. A focused commit keeps the review small. A complete description provides the reasoning plus your local test evidence.

In this step, get ready to:
  • Create a focused commit containing only the two intended Markdown files.
  • Push the commit to your published fork branch.
  • Open a public pull request with a completed template.
Create the focused commit

A commit records one reviewable unit of work. This commit should contain only the guidance requested by issue #113.

  • Switch back to GitHub Desktop from earlier.
  • Select the Changes tab.
  • Confirm that only docs/WEEKLY_HELP_THREAD.md and docs/MAINTAINER_PLAYBOOK.md are selected.
  • Review the diff for both selected files.
  • Enter docs: add discussion-to-issue guidance in the Summary field.
  • Click Commit to docs/discussion-to-issue-guide.

That is the first handoff complete. Your current branch now contains the focused documentation commit with no unrelated files.

Seeing an unrelated file?

  • Leave node_modules unselected because installed dependencies do not belong in this documentation commit.
  • Leave unrelated package files unselected if dependency installation created an unexpected tracked change.
  • Ask for help with the diff before publishing it: Help me identify which files belong in my focused documentation commit.
Push and preview the pull request

Pushing copies the new commit to the published branch on your fork. The pull request preview then compares that branch with the parent repository's main branch.

  • Click Push origin in GitHub Desktop.

Your latest commit is now available on the remote fork branch. GitHub Desktop should no longer show that commit as waiting to be pushed.

Push blocked?

  • Confirm that GitHub Desktop still shows docs/discussion-to-issue-guide as the current branch.
  • Confirm that GitHub Desktop still uses the authenticated account that owns your fork.
  • Get help with the exact message you see: Help me resolve this GitHub Desktop push problem.

The final button in the preview opens GitHub in your browser. You complete the pull request form there.

  • Click Preview Pull Request in GitHub Desktop.
  • Confirm that the base branch is main.
  • Confirm that the source branch is docs/discussion-to-issue-guide.
  • Click Create Pull Request in the preview.

Your browser should open the new pull request form for the parent repository.

Complete and verify the pull request

The repository template gives the maintainer the context needed to review your change. Your answers should connect the documentation edits to issue #113 plus the validation you already completed.

  • Use What changed? to summarize the guidance added to both Markdown files.
  • Use Why does this help? to explain how the guidance helps maintainers turn a useful Discussion into a scoped issue.
  • Use Testing to record that npm run check completed successfully.
  • Mark the I ran npm run check checkbox.
  • Replace the placeholder under Related issue with Closes #113.

Why does the template matter?

Each section answers one review question. The maintainer can see the scope, purpose, test evidence, and linked issue without searching through earlier comments.

Before you create the pull request, do you expect its changed-files list to contain anything beyond the two Markdown guides?

  • Click Create Pull Request on GitHub.

You should land on the public pull request page for your contribution.

  • Confirm that the pull request targets P-r-e-m-i-u-m/open-source-starter-lab on branch main.
  • Review the changed-files list for docs/WEEKLY_HELP_THREAD.md plus docs/MAINTAINER_PLAYBOOK.md.
  • Review the CI status for checks that are running or passing.

You should see only the two intended Markdown files. The description should contain all four template sections, successful test evidence, a marked checkbox, and Closes #113.

Pull request details look wrong?

  • Confirm that the target repository is P-r-e-m-i-u-m/open-source-starter-lab.
  • Confirm that the source branch is docs/discussion-to-issue-guide from your fork.
  • Get help before asking for review: Help me check my pull request target, files, and description.

You completed the full contribution loop. Maintainers can now review a focused public change with its purpose, validation evidence, and linked issue in one place.

Secret mission

Add a Worked Conversion Example

Turn one informal Discussion comment into a compact ready-issue example. Add it to the existing pull request as a second focused commit.

Clean Up Your Resources

Clean Up Your Resources

GitHub Free is $0 USD per month. Your local clone only occupies disk space on your Windows computer.

Decide whether to keep your resources available for maintainer review, pause your local work, or delete everything after the pull request is closed or merged.

Resources you used:

  • The local clone at your learner-selected Windows path, including its node_modules directory.
  • Your public fork of P-r-e-m-i-u-m/open-source-starter-lab.
  • The published topic branch named docs/discussion-to-issue-guide.
  • The public pull request against the parent repository's main branch.

Keep everything running

No action needed. Choose this if the pull request is still open for maintainer review.

  • Leave the pull request open so maintainers can review your documentation.
  • Respond to any feedback on the pull request.
  • Keep docs/discussion-to-issue-guide available for follow-up commits.
  • Keep the fork connected to the parent repository.
  • Keep the local clone available for future edits.

Pause - I'll come back to this later

Shut down your local tools to pause the work. Your files and public contribution remain available when you return.

  • Close Visual Studio Code.
  • Close GitHub Desktop.
  • Keep the local clone at your learner-selected Windows path.
  • Leave the fork available on GitHub.
  • Leave docs/discussion-to-issue-guide published.
  • Return to the existing pull request when you are ready to respond to feedback.

Delete - I don't want to use this again

Removing the fork and local clone is a permanent cleanup step. The safest point to do this is after the pull request is closed or merged.

  • Check the existing pull request conversation page for a closed or merged status.
  • Close the pull request from that page if it remains open after you decide to stop the review.
  • Open the branch list for your fork on GitHub.
  • Delete docs/discussion-to-issue-guide from the branch list.
  • Open the repository settings for your fork.
  • Use the repository deletion control to remove the fork.

That's the online cleanup complete. Your local clone is the final resource to remove.

  • Close Visual Studio Code.
  • Close GitHub Desktop.
  • Open the Windows folder browser from Windows search.
  • Navigate to the learner-selected Windows path that contains the local clone.
  • Delete the local clone of P-r-e-m-i-u-m/open-source-starter-lab.
  • Empty the Windows recycle bin to reclaim the disk space used by the clone and its dependencies.

You should no longer see the local clone at the learner-selected Windows path. Its node_modules directory is removed with it.

Nice Work!

Nice Work!

You did it. Your public documentation pull request now gives Open Source Starter Lab maintainers a concise path from a useful GitHub Discussion to a scoped issue.

You've learned how to:

  • Claim a live documentation issue without duplicating another contributor's work. You also used GitHub Desktop to cross the upstream permission boundary with a fork.
  • Create a focused documentation branch that changes only the two requested files. You previewed the Markdown guidance in Visual Studio Code before validating it locally.
  • Open a review-ready pull request against the parent repository. Your pull request includes test evidence plus a linked issue. It also shows visible CI checks.
  • Secret Mission: Added a compact before-and-after conversion example through a second commit on the same pull request.

Ready to quiz yourself?