Write Clear Pull Request Descriptions with Voice Dictation

The change is ready, but the pull request description still says “update docs.” You remember why you made it, which detail needs a second opinion, and what you checked. Putting that context into a blank text box can feel like starting another task.

Voice dictation offers a practical starting point: explain the change as if a teammate were beside you, then edit the transcript into a description they can scan. GitHub’s review guidance also emphasizes explaining a change’s context. The following voice-first routine turns your own explanation into a draft.

1. Keep the change in view while you speak

On your Mac, open the changed files beside a scratch document or the pull request form. Read the actual change before dictating. Describe what is in this request, not everything you planned during the day.

Start with one sentence about the outcome: “This adds a setup checklist to the contributor guide.” Leave exact filenames, issue numbers, and commands for the editing pass; copying those details is often simpler than spelling them aloud.

2. Answer five short prompts

Speak in small sections, pausing between these questions:

• What changed? Name the visible result, not every edit.
• Why now? Describe the problem or missing context.
• Where should review start? Point to the part that needs attention.
• What did I check? State completed checks and their actual outcomes.
• What remains open? Separate questions, untested cases, and work outside this request.

If the repository already has a description template, use its headings. Dictation fills the draft; it does not need to replace your team’s format.

3. Edit the spoken explanation into a review guide

Consider this fictional documentation change, unrelated to TypeFree’s product features:

I added a setup checklist because the contributor guide assumed the reader had already prepared their environment. Start with the prerequisites section. I opened the links in the preview and they worked, but I have not followed the setup on a clean machine. I would like someone to check whether the prerequisites are complete. The installation commands have not changed.

After editing, the description could read:

Summary: Add a setup checklist to the contributor guide. Installation commands are unchanged.

Reason: Make the required preparation explicit for first-time contributors.

Review focus: Check the prerequisites section for missing steps.

Checks completed: Opened the checklist links in the documentation preview; each reached its intended destination.

Not checked: Following the full setup on a clean machine.

This is a sample, not a ready-made test report. Replace every check with your own evidence. “I will test this” belongs under pending work, not completed validation.

4. Keep precise details precise

Copy filenames and links from the source, then check that each belongs to this change. Listen for meaning when reviewing the text: “commands changed” and “commands have not changed” describe opposite scopes.

Remove the story of every attempted solution unless it explains an important decision. A reviewer needs the reasoning behind the final change, not a transcript of the entire afternoon. Keep unresolved questions visible instead of polishing them into confident claims.

5. Finish with a specific request

Replace “any thoughts?” with a question such as “Does this prerequisites list include everything a new contributor needs?” Then reread the description against the changed files and check results before sharing it.

For related writing tasks, try clearer bug reports and documentation drafts by voice.

TypeFree is a simple way to turn speech into editable text and write faster. Try it for your next pull request description: speak the explanation, add exact references, and review the text before posting.