Dictating Code Comments That People Actually Want to Read

Most developers write code comments the same way: reluctantly, at the end, in the shortest form possible. Not because they do not value documentation, but because switching from typing code to typing prose is a context switch that kills momentum. Dictation removes that friction.

Why Comments End Up Useless

A comment that says // handle error tells the next developer nothing. It was written by someone who wanted to be done and move on. A comment that explains why the error happens, what the edge case is, and what was tried before this solution, that is the comment that saves an hour of debugging six months later.

The difference between those two comments is not knowledge. The developer who wrote the first one knew all of that context. They just did not want to type three paragraphs.

With dictation, three paragraphs takes about 90 seconds to speak. The knowledge that was about to disappear gets captured instead.

What to Dictate and What to Type

Voice is not the right tool for every part of a developer's work. Syntax, variable names, function signatures, anything with precise characters or formatting, those stay on the keyboard.

But prose belongs to your voice. That includes:

• Inline comments explaining non-obvious decisions
• README sections describing architecture or setup
• Pull request descriptions
• Tickets and bug reports
• Slack messages and async updates
• Meeting notes and technical specs

These are all tasks where speaking is faster and the output is often better. Spoken explanations tend to be more natural and easier to follow than typed ones that got compressed in the interest of speed.

The Workflow in Practice

Here is a concrete setup. You are working in your editor. You finish a tricky function and want to leave a real explanation for whoever reads this next, including future you.

Without lifting your hands from the keyboard, trigger VoiceInk with your hotkey, and say the comment out loud as if you were explaining it to a colleague. Stop the recording. The text appears in your editor at the cursor position. Clean up the line breaks if needed, add comment syntax, and move on.

Total time: under two minutes for a comment that would have taken ten minutes to type, or that you would have skipped entirely.

Documentation That Actually Gets Written

The biggest documentation problem is not quality. It is existence. Docs that never get written cannot be improved. The real enemy of good documentation is the activation energy required to start.

When dictating a README section takes three minutes instead of fifteen, you do it. When explaining an architectural decision in a PR description takes one minute of talking, you include it. The bar drops low enough that the work happens.

Several developers who use VoiceInk report that their async communication improved as a side effect. Dictated Slack messages are longer and more complete than typed ones. Fewer follow-up questions, fewer misunderstandings, less back-and-forth.

Getting Accurate Output for Technical Content

Technical dictation does require some adjustment. Speak clearly around jargon, acronyms, and library names. If a term consistently gets transcribed wrong, you have a few options: spell it out the first time, pause briefly before it, or just fix it manually in your editor afterward.

The correction overhead is small. On a 200-word comment, you might fix two or three words. That is still faster than typing 200 words from scratch.

The Bigger Picture

Developers are often the most resistant to trying dictation because they associate voice with inaccuracy. That reputation is outdated. Modern local transcription is fast and accurate enough for real work.

The developers who stick with it tend to say the same thing: they wish they had started earlier. The knowledge they used to let evaporate is now captured, and the physical toll of a full day at the keyboard is noticeably lower.

If you write code, your prose work deserves a faster input method. Give it a week and see what your documentation looks like.