Dictating Documentation: A Developer's Honest Take

Nobody writes documentation because they love writing documentation. They write it because shipping without it causes problems later, or because a teammate asked, or because the PR template requires it. The actual act of writing the docs is a tax on top of the real work.

Voice dictation doesn't change that calculus entirely. But it removes one specific friction that makes docs feel worse than they are: the cost of switching from thinking to writing.

The Context Switch Problem

When you're deep in a codebase and you stop to write a comment or a README section, you're not just switching tasks. You're switching modalities. You go from reading, navigating, and executing to composing prose, which uses different mental machinery and often requires a cold start.

That cold start is where documentation time actually goes. It's not the writing itself. It's the 90 seconds of sitting there, cursor blinking, trying to remember what you were going to say about the function you just finished.

Dictation shortens that gap. You can speak about code the same way you'd explain it to a colleague, in real time, without waiting for your fingers to catch up. The words come out as fast as the explanation does.

What Works Well for Dictation

Some things translate to voice better than others. The sweet spots:

Inline comments. Explaining what a block of code does, why a particular approach was chosen, or what edge case a conditional handles. These are conversational by nature. "This function checks for a null user before calling the API because the endpoint returns a 500 instead of a 400" is faster to say than to type.

README sections. Especially the parts that describe intent rather than syntax: what the project does, why it exists, how to think about the architecture. Those sections benefit from a natural voice.

Meeting notes and async updates. After a technical discussion, speaking a summary into a notes app while the conversation is still in your head is faster than writing it up an hour later from memory.

Ticket descriptions and PR summaries. The context that gets lost between implementation and review. Dictating a quick walkthrough of what changed and why takes 90 seconds and saves ten minutes of back-and-forth.

What Still Needs Typing

Code itself stays in the keyboard. Variable names, function signatures, anything that requires exact syntax is slower and more error-prone by voice. The goal isn't to stop typing. It's to use typing only where it has a real advantage.

Same with anything highly structured, tables, numbered lists with specific formatting, anything where the shape of the text matters as much as the content. Dictate the raw content, then format it by hand.

A Practical Setup

For in-editor documentation, a tool like VoiceInk works well because it types directly into whatever field has focus. You don't need a separate dictation window or a paste step. Activate it with a hotkey, speak the comment, and it appears in the editor. That frictionlessness matters. If the process has more than two steps, most developers will skip it.

For longer external docs, a notes app or a plain text file works better. Speak the whole section, rough and complete, then edit. Trying to dictate and edit simultaneously is slower than doing them in sequence.

The Broader Shift

Developers who dictate documentation tend to write more of it. Not because dictation is fun, but because the cost goes down. When writing a comment takes 15 seconds instead of 45, the mental math changes. You do it more often. The codebase gets better annotated. Future you is less confused.

That's the actual value. Not speed for its own sake, but removing enough friction that the thing you already know you should be doing becomes the thing you actually do.

If your docs are always the last thing on the list, it might be worth trying a different input method for a week.