Dictating Code Comments and Docs Without Breaking Flow

Developers write a surprising amount of prose. Docstrings, inline comments, README files, pull request descriptions, Jira tickets, Confluence pages, Slack explanations to non-technical stakeholders. None of it is code, all of it takes time, and most of it gets skimped on because typing it out feels like friction.

Voice dictation doesn't replace typing code. It handles the prose that wraps around it.

Where Dictation Fits in a Dev Workflow

The clearest win is documentation. Writing a detailed README or a function docstring while you still understand what the code does is the right time to do it. But sitting down to type out a full explanation right after finishing the implementation is its own kind of mental tax.

Speaking the documentation is faster and often clearer. You already know what the function does. Explaining it out loud comes naturally. Typing a formal explanation requires more effort than the explanation itself should take.

Pull request descriptions are another good target. A clear PR description explains what changed, why it changed, and what the reviewer should look at. That's a two or three paragraph writing task. Dictate it in 90 seconds, clean it up in 30, and move on.

The Setup for Developers

The key requirement is that dictation drops text wherever your cursor is, without requiring a window switch or a separate app. VoiceInk works this way: press the hotkey, speak, and the words appear in your editor, your terminal notes, your browser, wherever focus is.

That directness matters for developers. Context switching is expensive. If dictation requires you to leave your editor, open a separate window, speak, copy, paste, and return, the friction kills the habit. The whole point is to stay inside the tool you're already using.

Commenting While You Code

One pattern that works well: write the comment before the code. Speak a one or two sentence explanation of what you're about to implement, let it land as a comment in your editor, then write the code beneath it. This is already good practice for clarity, and dictation makes it fast enough that it doesn't feel like overhead.

For complex sections, some developers speak a longer block comment explaining the logic and edge cases, then use that comment as their own specification while coding. The comment serves double duty as thinking-out-loud and as documentation.

Bug Reports and Postmortems

Writing up a bug you just fixed is the worst time to write it up. You're tired of looking at it and you want to move on. But the details are fresher than they'll ever be again.

Dictate a rough summary immediately after the fix: what the bug was, where it lived, what the root cause turned out to be, what you changed. Don't worry about formatting. Get the information down. You can clean up the language later; you cannot reconstruct context you've already lost.

The same applies to incident postmortems. Speaking through what happened while the timeline is clear produces a better starting document than staring at a blank Confluence page three days later.

What Not to Dictate

Code itself is almost never worth dictating. Variable names, function calls, syntax: these require precision that typed input handles better. Punctuation like brackets, semicolons, and operators is awkward to say out loud and error-prone.

Anything that goes directly into a shell or a compiler belongs at the keyboard. Dictation is for natural language. Keep the boundary clean.

The Real Benefit

The documentation problem in software is largely a motivation problem. Developers know they should write more comments, better READMEs, clearer PR descriptions. They also know it's slow and unglamorous.

Dictation doesn't make documentation glamorous. It makes it fast enough that the excuse of "it takes too long" disappears. If you can explain your code to a colleague in two minutes of talking, you can dictate a useful comment in the same two minutes.

If your project's documentation is rougher than it should be, try speaking the next thing you'd normally skip. It takes less time than you think.