Dictating Code Comments and Docs: A Developer's Guide

Developers don't skip documentation because they don't care. They skip it because it's slow, it's context-switching, and by the time you've finished a function you just want to move on to the next one. The code is done. Writing about the code feels like doing the work twice.

Voice dictation doesn't fix everything about that problem, but it fixes the speed part, and speed is most of the problem.

What Developers Actually Need to Dictate

You probably don't want to dictate code itself. Syntax is too precise, variable names too specific, and speaking a bracket-heavy function would be miserable. That's not the use case.

What you can dictate, quickly and usefully:

• Inline comments explaining why a decision was made
• Function and method docstrings
• README sections and setup instructions
• Architecture notes and decision records
• Slack messages and PR descriptions
• Tickets and bug reports

That's a large slice of the non-code work in a developer's day. Most of it is prose. Prose is exactly what voice dictation handles well.

The Inline Comment Problem

Inline comments are the most skipped documentation of all. They take maybe thirty seconds to type, but that's thirty seconds of context-switching when you're deep in a flow state. So you skip them, and six months later you're reading your own code wondering what you were thinking.

With a tool like VoiceInk, adding a comment takes about five seconds. Position your cursor, press the key, say "this function handles rate limiting for the API client, returns early if the token bucket is empty," and it's done. You don't move your hands from the keyboard. You barely break flow.

Five seconds is low enough friction that you'll actually do it.

Dictating Docstrings

Docstrings are longer and more structured than inline comments, which makes them even better candidates for dictation. Speaking is faster than typing, and docstrings are pure prose, no special syntax beyond the opening and closing quotes.

A pattern that works: write the function first, then position your cursor in the docstring block, press your dictation key, and describe what the function does as if you're explaining it to a colleague. "Takes a user ID and an optional date range, queries the events table, and returns a list of event objects sorted by timestamp. Raises a ValueError if the user ID is not found."

That took about eight seconds to say. It would have taken forty-five to type, and you probably would have abbreviated it.

Architecture Notes and Decision Records

These are where dictation really earns its place. Architecture decision records are long, they're prose-heavy, and they're the kind of thing that accumulates as a task in your backlog for weeks because writing them feels like a lot of work.

Try dictating one. Open a markdown file, speak through the context, the decision, and the consequences. You'll produce a rough draft in five minutes that would have taken thirty to type. Then edit it. The total time is still less than writing it cold.

The same applies to runbooks, onboarding docs, and internal wikis. Any time a document has been sitting in "draft" status because you just haven't gotten around to writing it, dictation is the answer.

Setting It Up

VoiceInk works across all Mac apps, which means it works in your editor, your terminal notes, your browser-based ticket system, your Slack window. You configure a hotkey, and from that point on dictation is available everywhere without switching context.

For development work specifically, a good condenser microphone makes a real difference. You don't need anything expensive, but a dedicated mic beats laptop audio for accuracy when you're in a noisy environment.

Start With One Thing

Pick one category of documentation you always skip. Inline comments, PR descriptions, whatever it is. For one week, dictate every one of those instead of typing them.

By the end of the week you'll have more documentation than you've written in the past month, and it will have cost you almost no extra time. That's the trade.

The code will still be there when you're done talking about it.