How to Dictate Pull Request Descriptions (and Review Comments) by Voice

Short answer: Put your cursor in the PR description box, hold a dictation hotkey, and explain the change the way you would to a reviewer sitting next to you: what changed, why, how to test it, what could break. Type the identifiers, file paths, and version numbers by hand; speak everything else. Edit, then submit.

Open the last ten pull requests your team merged and read the descriptions. Some will be a template with the headings still in it and nothing underneath. Some will be one line: "fix login bug" or "address review comments." A few will be genuinely useful, and those were probably written by the same one or two people every time.

The usual diagnosis is discipline. Engineers should care more about documentation, the argument goes, so we add a PR template, a lint rule, a checklist, and the descriptions get slightly longer and no more useful. The actual problem is simpler and less moral than that. A pull request description is a translation task from a diff into prose, and it has to be produced at typing speed, at the exact moment the author has finished the interesting part and wants to move on, inside a toolchain that is optimized for editing code and not for writing sentences.

Change the input cost and the descriptions change. That is what this guide is about: how to dictate a pull request description, and the review comments that follow it, so that writing the prose takes about as long as saying it out loud.

Why PR descriptions are bad (it is not laziness)

Consider what happens when a developer opens a PR. They have just spent an hour, a day, or a week inside the change. They understand it completely. Every design decision, every path not taken, every risk they thought about and dismissed is fully loaded in their head. Then they push, open the browser, and stare at an empty text box.

At this point they can explain the change out loud, fluently, in about ninety seconds. Anyone who has done a code walkthrough on a call knows this. Ask "so what does this PR do?" and you get a clear, well-organized answer, with the why and the risk and the testing notes, in the natural order a listener needs them.

Typing that same explanation takes ten to twenty minutes for most people. Adults type around 40 words per minute on average, and even a proficient typist at 80 to 100 WPM is fast for code and slower for prose, because prose has no autocomplete. Meanwhile speech runs at 130 to 150 words per minute with no effort at all. So the ninety-second explanation becomes a fifteen-minute writing task, and it competes with the next ticket, the Slack thread that piled up, and the natural desire to be done. The template headings win by default.

The other cost is attention. Explaining a change requires holding its shape in your head. Typing requires attention on the keys and the screen. For most people the second interrupts the first, which is why typed descriptions read like a list of files touched rather than an explanation of a change: the list is what you can produce while your attention is on your fingers.

Speaking removes both costs. You explain the change at the speed you think, with your attention on the change and not on the keyboard, and the words appear at the cursor. What comes out is closer to what you would say on the walkthrough call, which is exactly what the reviewer wanted in the first place.

What a good PR description contains

Before the how, the what. There is no single right template, but nearly every useful description covers four things, and they map cleanly onto how people naturally talk about their work:

1. What changed. One or two sentences, in user or system terms rather than file terms. "Retries the payment webhook up to three times with backoff instead of failing on the first timeout" beats "updated webhook handler."
2. Why. The ticket, the incident, the customer complaint, the design decision. This is the part that disappears from typed descriptions first, and the part that matters most six months later when someone runs git blame and wants to know what you were thinking.
3. How to test it. The steps a reviewer can follow to see it working, plus anything they cannot see from the diff: a feature flag to enable, a fixture to load, an environment variable.
4. Risk and rollout. What could break, what you deliberately did not do, whether it needs a migration, whether it can be reverted cleanly.

Notice that all four are prose. Only the title and the occasional identifier are anything else. That ratio is why voice fits this artifact so well, and it is the same reason it fits bug reports and release notes: the parts that go unwritten are the parts that are expensive to type and cheap to say.

The setup on a Mac

Voice Keyboard Pro lives in the menu bar and works in every app, including the browser tab where your PR lives, your terminal, and your editor. Hold the hotkey, speak, release, and the text lands at the cursor. There is nothing to install in GitHub, GitLab, Bitbucket, or your IDE, and no plugin to keep updated.

Two setup decisions matter for developers specifically:

• Choose a hotkey that no tool already uses. Editors and browsers own most modifier combinations. A dedicated key such as F13 through F19, or a combination you have confirmed is unbound in your IDE, means the dictation hotkey never fights a shortcut you rely on.
• Put the cursor in the box first. Dictation types where the cursor is. If focus is on the page rather than in the description field, the words go nowhere useful, or worse, trigger the single-key shortcuts that GitHub and GitLab expose when no text field is focused. Click into the field, see the caret blink, then hold the hotkey.

Our guide to dictating in GitHub covers the interface details, and the same principles carry to GitLab and any other web-based review tool.

The rule that prevents silent errors: speak the prose, type the identifiers

This is the single most important habit for dictating anything technical. Voice Keyboard Pro's transcription engine is very good at sentences. It is not the right tool for PaymentWebhookRetryPolicy, src/api/webhooks/handler.ts, v2.4.11, or #4821, and no speech tool is, because those are not words. They are strings with exact casing, punctuation, and digits, and a plausible-looking near miss is worse than an obvious error.

The danger is that identifier errors read as correct. If the transcription produces "2.4.1" when you said "2.4.11," nobody notices until someone deploys the wrong thing. If it renders a function name with the wrong casing, the reviewer searching the codebase for it finds nothing and assumes you renamed it. These are silent failures, and the way to avoid them is not to try harder with pronunciation. It is to split the work: speak every sentence, and when you reach an identifier, release the hotkey, type it, and hold the hotkey again for the next sentence.

In practice this is faster than it sounds, because a PR description is mostly sentences with a handful of identifiers sprinkled through it. The rhythm becomes: hold, say a sentence, release, type RetryPolicy, hold, say the next sentence. It takes about a day to stop thinking about it. The same rule applies to code comments, commit messages, and anything else where prose and identifiers share a line.

Dictating the description, section by section

Here is how the four parts go when you dictate them. The framing that helps most is to imagine the reviewer is on a call and just asked you to walk them through it.

The title: type it

Titles are short, often follow a convention like a ticket prefix or a conventional-commits type, and frequently include an identifier. Type them. Dictation buys you nothing on eight words and costs you a correction if the convention gets mangled.

The summary: answer "what does this do?"

Click into the description body, hold the hotkey, and answer the question out loud. Do not compose in your head first. Just say it: "This changes the payment webhook handler to retry up to three times with exponential backoff when the downstream call times out, instead of marking the payment failed on the first timeout." Release. Read it. Type any identifiers you skipped. That is the summary.

People consistently find that the spoken version is better than the typed one would have been, because it is written in the vocabulary of the system rather than the vocabulary of the diff. When you type, you look at the files and describe files. When you speak, you look at nothing and describe behavior.

The why: say what you would say if someone asked

Hold again and explain the reason. "We had three incidents last month where a transient timeout on the provider side caused a payment to be marked failed even though it later succeeded, which meant customers were charged and told the charge failed. The ticket is linked below." This is the section that typed descriptions almost always omit, and it is thirty seconds to say.

If there was a decision, say the decision and the alternative you rejected. "I considered making this idempotent on the provider side instead, but we do not control that, so retrying on ours was the only option available this quarter." A reviewer who reads that will not ask the question, and the person reading the history next year will not have to guess.

How to test: dictate the steps while you do them

The best testing sections are written by someone actually performing the test, because a test written from memory skips the step the author does automatically. So run through it: open the app, hold the hotkey, say "Enable the payment retry flag in the local config," release, do it, hold, "trigger a checkout with the sandbox card that simulates a timeout," release, do it, and so on. Each step is one hold. The result is a numbered list a reviewer can follow, produced in the time it took you to test your own change.

Numbers, flags, and card values get typed, per the rule above.

Risk, rollout, and what you deliberately did not do

This section is where speaking really pays for itself, because it is conditional and hedged, and conditionals are expensive to type. "This should be safe to deploy without a migration. The one thing I would watch is the retry queue depth in the first hour, because if the provider has a real outage rather than a transient one we will retry every payment three times. There is a follow-up ticket to add a circuit breaker; I did not include it here to keep the diff reviewable." That is four sentences and about twenty seconds. Typed, it is the paragraph most people never write.

The process change: describe while the context is loaded

The single most effective change is not a tool. It is timing. The moment you understand a change best is right after you finish it, and the moment you least want to write is also right after you finish it. Dictation resolves the conflict, because a ninety-second spoken explanation does not feel like writing.

So make it a reflex: push the branch, open the PR page, hold the hotkey, and talk for a minute and a half before doing anything else. If the PR is large and built over several days, dictate a sentence or two into a scratch note at the end of each day while that day's part is fresh, then assemble the description from those on the day you open the PR. Either way, the description becomes an editing job on words that already exist rather than a writing job that starts from nothing.

The other benefit is that speaking your reasoning out loud tends to surface the flaws in it. Engineers already know this as the rubber duck effect. Dictating a PR description is a rubber duck session that leaves a document behind.

Dictating code review comments

The reviewer's side has the same economics with one extra twist: tone. Review comments are famously terse, and the terseness is a typing artifact. "why not use the existing helper" takes six words to type. "I think there is an existing helper for this in the utils module that handles the null case, which might be worth reusing so we do not end up with two versions to maintain. Not blocking if there is a reason it does not fit here." takes about ten seconds to say, and it reads like a colleague rather than a linter.

Speaking your review comments makes them longer, warmer, and more complete without any deliberate effort to be nice, because a spoken sentence naturally carries its own context and hedging. That is not softness. A comment that explains its reasoning is more likely to be acted on, and less likely to start a thread.

Practical notes for reviewing by voice:

• Click into the line comment box, hold, say the comment, release, then read it before you submit. Correct any identifier by typing it.
• Reviews often involve a dozen small comments. Each one is one hold. The overall review time drops noticeably, and the comments get better rather than worse as you go, which is the opposite of what happens when typing fatigue sets in.
• For the summary comment on an approval or a request for changes, do the same thing you did for the description: imagine you are telling the author on a call, and say it.
• Replies to review comments on your own PR are a good place to start if you are new to dictation. They are short, conversational, and low-stakes.

Traps in GitHub, GitLab, and similar tools

A few interface behaviors catch people the first day.

Selection is not insertion. If you highlight a paragraph in the description and dictate, expecting to replace it, most web text areas will insert at the caret rather than replace the selection, or will replace it, depending on the field. Check once in your tool, and when in doubt, delete first and dictate into empty space.

Single-key shortcuts. GitHub, GitLab, and many review tools have keyboard shortcuts that fire on bare letters when no text field is focused. If your focus drifts out of the description box and you type an identifier, you may open a search box, jump to a different tab, or trigger an action instead of typing. This is another reason a dedicated hotkey and a glance at the caret before you hold are worth the habit.

List continuation. Some markdown editors continue a numbered or bulleted list when you press Return. If you dictate "one, enable the flag" and then press Return and dictate the next step, you can end up with doubled numbering or stray bullets. Either let the editor number for you and dictate the content only, or dictate the whole list into a plain scratch field first and paste it in.

Submit shortcuts. Comment boxes usually submit on a modifier-plus-Return combination rather than plain Return, but check yours. Sending a half-finished review comment is embarrassing in a way that a typo is not.

PR templates. A template with headings is a gift for dictation: put the cursor under each heading, hold, say that section, release, move to the next. One hold per heading. Delete the headings you have nothing to say under rather than leaving them empty.

Smart Vocabulary for the names you say out loud

Every team has words its transcription will not know at first: the product name, the internal service names, the customer whose name is on the incident, the acronyms that only mean something inside the company. Smart Vocabulary in the Mac app is a personal dictionary with replacement rules, so once you have corrected a term twice you can add it and it comes out right from then on.

One deliberate caveat for developers: keep Smart Vocabulary for things you would say out loud in a meeting. Service names, team names, product names, customer names, acronyms. Do not try to make it a substitute for typing mixed-case code identifiers. PaymentWebhookRetryPolicy should be typed every time, because it will change, because there are dozens like it, and because a replacement rule that fires when you did not mean it is exactly the kind of silent error the type-the-identifiers rule exists to prevent. Our post on custom vocabulary that learns your words goes into how to build a list that helps rather than one that surprises you.

Reviewing from your phone

Plenty of review happens on a phone: the approval on the way in, the reply to a comment while waiting for a coffee, the "looks good, one question" that unblocks a teammate in another timezone. Typing a considered review comment on a phone keyboard is exactly the situation where terse comments come from.

The Voice Keyboard Pro iPhone keyboard puts a mic button in the keyboard itself, so it works inside the GitHub or GitLab mobile app or their web views in Safari. Tap the mic, say the comment, and it types where the cursor is. If a sentence comes out wrong, Voice Edit lets you speak the correction ("change 'the helper' to 'the null-safe helper'") instead of hunting for the right spot with your thumb. Type any identifier the same way you would on the Mac. And if the comment involves anything sensitive, remember that dictation is audible; the train is not the place to narrate an incident.

Honest limits

It is worth being clear about what dictation does not do here, because the value depends on using it for the right part of the job.

• It does not read your diff. Voice Keyboard Pro types what you say. It does not summarize the change, generate the description, or know what files you touched. That is by design: the description should be your understanding of the change, and the process of saying it out loud is part of what makes it good.
• It does not integrate with your repository. There is no GitHub app, no bot, no permission to your code. It types text at the cursor in whatever is in front of you.
• Do not dictate code. Identifiers, paths, snippets, commands: type them. Speak the sentences around them.
• It needs a connection. Transcription runs on our servers, so an offline flight is not the moment.
• It is audible. Open-plan offices and shared spaces are a real constraint. Many people dictate the description at home or in a room and type the quick review replies at their desk.
• Privacy. As of the May 2026 privacy update, our server stores only operational pings. It does not store your audio, and it does not store the content of what you dictated. That said, if your codebase is under an NDA or a strict security policy, read the policy yourself before dictating anything about it. Nobody else can make that determination for you.

A first week that actually sticks

Do not try to change everything at once. A sequence that works:

1. Day one: dictate only replies to review comments on your own PRs. Short, conversational, forgiving.
2. Day two: dictate the "why" section of your next PR description. Type everything else as usual. Notice that this section, which you used to skip, now exists.
3. Day three: dictate the whole description, section by section, using the type-the-identifiers rule. Read it back before submitting and count the corrections. Add any repeated names to Smart Vocabulary.
4. Day four: review a PR by voice. Notice the length and tone of your comments compared with last week.
5. Day five: time yourself. Push, open the PR, hold, talk, edit, submit. Compare with the last time you did the same thing by typing.

Most people find by the end of that week that the descriptions are longer, more useful, and faster to produce, and that the improvement came from a change in input rather than a change in character.

Frequently asked questions

Does this work in the terminal, for commit messages?

Yes. Voice Keyboard Pro types at the cursor system-wide, including in a terminal editor session. The same speak-the-prose, type-the-identifiers rule applies. We have a separate guide to dictating git commit messages in the terminal.

Will dictated descriptions be too long?

Sometimes the first draft is. The fix is editing, and editing is mostly deleting, which is the fastest kind of editing there is. A dictated description that needs trimming is a better starting point than an empty template that needs writing.

Can I use it with conventional commits or a strict PR template?

Yes. Type the structured parts (the type prefix, the scope, the ticket reference, the headings) and dictate the prose under them. The convention constrains the format, not the sentences.

What about pair or mob programming?

Dictating the PR description at the end of a pairing session, with the pair listening and interrupting, produces some of the best descriptions we have seen. One person holds the key and talks; the other says "you forgot the migration." It is a walkthrough that leaves a document.

How much does it cost?

Voice Keyboard Pro has a free tier with daily limits, which is enough to try it on your next few PRs. Pro is $4.99 per month or $34.99 per year and removes the limits.

The next time you push a branch and open that empty description box, try it once: click in, hold the hotkey, and tell the reviewer what you did. Voice Keyboard Pro is free to try, and the ninety-second version of your explanation is the one your teammates wanted all along.