Dictating Code Comments and Docs: A Developer's Guide

Ask any developer what they skip when they are in flow, and documentation comes up every time. Not because it feels unimportant, but because switching from writing code to writing prose breaks something. The context shift is expensive, and the typing feels slow compared to what you were just doing.

Voice dictation does not fix the context shift. But it makes the prose side fast enough that the cost feels acceptable.

What Developers Actually Need to Dictate

Code itself is not a good target for voice. Variable names, bracket placement, and language syntax make spoken transcription impractical without a specialized tool. This is not where dictation helps.

What does work:

Inline comments. Explaining why a function works the way it does, what a regex is actually matching, or why a particular workaround exists. These are prose sentences and dictation handles them cleanly.

Docstrings. Parameter descriptions, return value explanations, usage examples written as text. Speaking a complete docstring is often faster than typing it and far more likely to actually happen.

README files. Installation steps, configuration options, architecture overviews. Most READMEs are abandoned because they feel like a second job. Talking through them, even roughly, produces something editable in minutes.

Commit messages. A good commit message explains what changed and why. Most developers write a four-word message and move on. Dictating a two-sentence message takes about eight seconds.

Slack messages and issue descriptions. Technical communication is writing. Dictating bug reports and PR comments reduces the overhead enough that they get written properly instead of abbreviated into ambiguity.

Setting Up for a Dev Workflow

The practical requirement is a tool that drops transcription into whatever you are typing in, without a mode switch. VoiceInk works well here because it is system-level on Mac. You can be in VS Code, iTerm, Notion, or Linear and invoke it with the same shortcut. The text lands at the cursor.

Set your shortcut to something you can hit with one hand while the other is on the mouse. Left-hand shortcuts work well if you are right-hand mousing.

For longer documentation, a separate markdown file open in your editor works better than trying to dictate directly into a dense code file. Dictate the prose, clean it up, then place it.

Handling Technical Terms

This is the friction point most developers hit first. Transcription stumbles on framework names, acronyms, and unusual proper nouns.

A few approaches that help:

Spell out acronyms the first time and let transcription catch them, then fix in editing. Most transcription engines learn common technical terms over time.

For things you say constantly, like your company name, specific function names, or framework terminology, check whether your dictation tool supports custom vocabulary or corrections. A few minutes of setup saves a lot of cleanup.

Keep editing passes fast by only cleaning up terminology and not rethinking the prose. The goal is documentation that exists and is accurate, not documentation that is beautifully written.

The Real Argument for Dictation in Development

Documentation that exists is infinitely more useful than documentation that does not. The bottleneck for most developers is not knowing what to write. It is the activation energy required to sit down and type it after already spending hours writing code.

Dictation lowers that activation energy. Talking through what a function does, why a decision was made, or how a system fits together takes almost no effort when you are already thinking about it. The thinking is done. You are just exporting it.

If you finish a feature and spend ninety seconds dictating a short explanation into the README before closing the file, that project is more useful to everyone who comes after you, including yourself six months from now.

Try it on the next function you write. Add the comment by speaking instead of typing. See how long it actually takes.