Dictating Code Comments and Docs Without Losing Focus

The worst time to write documentation is after you've finished the code. By then the context has faded, the subtle decisions are half-remembered, and the comments end up describing what the code does instead of why it does it. The best time to write it is when you're still inside the problem, which is exactly when typing feels like the most annoying thing to do.

Voice dictation solves that timing problem without adding much friction.

The Context Window Problem

When you're deep in a function, you are holding a lot of state in your head. You know why this variable is named what it's named. You know what edge case this conditional is guarding against. You know why you chose this approach over the obvious one.

That context is valuable. It is also fragile. Once you switch to writing, or finish the task and move on, it starts to dissolve. Most developers either skip the comment entirely or write a placeholder that says something like "handles the edge case" without recording what the edge case actually was.

Speaking While You Code

The practical approach is to dictate comments and notes in the same moment you're making the decision. You've just written a function. You understand it completely. You press a key, say what it does and why, and move on. Fifteen seconds. The context is captured.

With something like VoiceInk running on your Mac, the words appear directly in your editor wherever your cursor is. No switching windows, no opening a notes app, no breaking the mental thread. You speak, it types, you keep moving.

This works well for:

• Inline comments explaining non-obvious logic
• Function docstrings
• TODO notes with actual context attached
• README sections while a feature is still fresh
• Architecture notes in a separate markdown file

Dictating Longer Documentation

For longer docs, a slightly different approach works better. Instead of trying to dictate formatted markdown on the fly, speak a rough draft first. Just talk through what the library does, what the setup steps are, what the common gotchas are. Get the whole thing out in one pass, messy and unstructured.

Then edit. The structure and formatting work is faster to do by hand once the content exists. The bottleneck was never the markdown syntax. It was having nothing to start from.

A 400-word README section that would have taken 45 minutes to write from scratch can be spoken in four minutes and edited in ten. That ratio matters when documentation is always the last item on the list.

Handling Technical Vocabulary

The main friction developers report with dictation is technical vocabulary. Function names, library names, variable names in camelCase or snake_case, these don't always transcribe cleanly.

The practical workaround is to speak the description and then type the specific names. Say "this calls the" and then type getUserById rather than trying to dictate it. Hybrid input works well here. You're not choosing between voice and keyboard; you're using each for what it does well.

Most transcription improves with repetition and context too. If you say useState ten times, tools learn to recognize it.

The Bigger Habit

The developers who get the most out of voice dictation treat it as a capture tool, not a replacement for typing. They speak when they have something to say and type when they're working in code. The two modes coexist.

The result is codebases that are better documented not because the developer suddenly has more discipline, but because the cost of capturing context dropped low enough that it actually happens.

If your comments are currently one-liners and your README ends with "more docs coming soon," it might be worth trying dictation for a week. Not as a productivity experiment, just as a way to make the capture cheap enough to bother.