Dictating Code Comments and Docs: A Developer's Guide

Ask any developer why their codebase is under-documented and you'll hear the same answer: there wasn't time. That's partially true. But the deeper truth is that writing documentation feels disproportionately expensive compared to writing code. The keyboard friction is the same, but the reward feels smaller.

Voice changes that ratio. Talking through what a function does takes about 30 seconds. Typing the same explanation takes three minutes. That difference adds up to whether documentation gets written at all.

What to Dictate vs. What to Type

Not everything in a developer's workflow benefits from voice. Code itself is still faster to type, and trying to dictate syntax is painful. Variable names, function signatures, file paths: these belong at the keyboard.

What works well by voice:

• Inline comments explaining why a decision was made
• README sections describing architecture or setup
• Pull request descriptions
• Commit messages longer than one line
• Meeting notes during standups or design discussions
• Slack messages explaining a bug or a fix
• Personal technical notes and research logs

The pattern is: anything in natural language, dictate. Anything with strict syntax, type.

The Pull Request Problem

PR descriptions are one of the most under-invested parts of software development. Most developers write one sentence, or copy the ticket title, because the overhead of context-switching from code to prose feels high. The result is a review history that tells you what changed but not why.

Dictating a PR description takes about 90 seconds if you talk through what the change does, what you considered and rejected, and what a reviewer should pay attention to. That's the kind of documentation that actually helps teams move faster. It just never gets written because typing it feels like a project.

With a tool like VoiceInk, you press a shortcut, speak into whatever text field is focused, and release. No app switching, no copy-paste. The barrier drops low enough that you'll actually do it.

Capturing Ideas During Deep Work

The other place voice helps developers is capturing thoughts without breaking flow. You're deep in a problem and you notice something unrelated: a potential refactor, a question to ask someone, a thing you need to check later. Stopping to type it out is a context switch. Speaking it into a notes app takes three seconds.

This is especially useful for capturing the reasoning behind decisions while it's still fresh. "I'm using a cache here instead of recalculating because the dataset is large and this runs on every request" is the kind of comment that saves a future developer 20 minutes of archaeology. It takes five seconds to say. It almost never gets written because the typing cost feels too high in the moment.

Setting It Up

You want dictation to be available everywhere without switching apps. On a Mac, VoiceInk sits in the background and activates with a keypress. This means you can dictate into your terminal notes, your IDE's scratchpad, your browser, your Slack window, anywhere you can type.

For technical content, accuracy on proper nouns and brand names matters. Spend a few sessions correcting common misrecognitions and you'll see improvement. Saying "capital G, i, t" helps for ambiguous terms. Speaking clearly and at a measured pace produces better results than rushing.

The Documentation That Finally Gets Written

The goal here isn't perfect documentation. It's documentation that exists. A README written in ten minutes of talking is infinitely more useful than a perfectly structured one that never got started.

If you've been meaning to document a project, try talking through it instead of typing it. Set a timer for 15 minutes, press record or activate dictation, and explain the project out loud as if you're onboarding a new teammate. Then clean up the transcript. You'll have a working first draft before the timer goes off.