Dictating Code Comments and Docs: A Developer's Guide

Documentation does not get written because writing it is slower than not writing it. That is the honest version of the problem. It is not that developers do not understand its value. It is that switching from a flow state in the editor to a typing task feels expensive in a way that is hard to justify in the moment.

Voice dictation does not make documentation glamorous. It does make it fast enough to actually happen.

Where Dictation Fits in a Dev Workflow

Dictation is not useful for writing code itself. Syntax is too precise, variable names are too specific, and the mental model required is too different from natural speech. If you try to dictate Python, you will spend more time correcting output than you saved.

But documentation is natural language. So are code comments, pull request descriptions, commit messages longer than one line, Slack explanations of architectural decisions, and README files. All of these are written in the same prose you would speak in a meeting. That is where dictation earns its place.

A Practical Setup

Install VoiceInk and set a trigger key that does not conflict with your editor shortcuts. Right Option works well in VS Code and JetBrains IDEs because it does not overlap with common keybindings. Test it in a text file before using it in your actual workflow.

For inline comments, the process is simple: put your cursor on a blank line above the function, hold the trigger key, say the comment, release. Done in under ten seconds. That is faster than typing a three-line explanation, and you are more likely to say what the code actually does rather than what you think is obvious from reading it.

Writing Docstrings and Function Comments

Speak the way you would explain the function to a new teammate. "This function takes a user ID and returns the most recent session object, or None if no session exists." That sentence, spoken in four seconds, is a better docstring than what most developers produce after thirty seconds of typing, because typing invites brevity and brevity invites vagueness.

For more structured formats, like JSDoc or Python docstrings with typed parameters, dictate the prose sections and type the structured fields. The parameter types and return annotations are short enough that dictation overhead is not worth it. The description fields are where you should be talking.

Pull Request Descriptions

This is one of the highest-value use cases for developer dictation. A good PR description explains what the change does, why it was made, and what a reviewer should pay attention to. Most PR descriptions are one sentence because writing more feels like too much work.

With dictation, a detailed PR description takes 45 to 90 seconds. Open the description field, hold the trigger key, and explain the change out loud the way you would in a standup. The words come faster when you speak them because you are not writing, you are explaining.

Architecture Notes and Decision Records

Architectural decisions deserve to be documented at the time they are made, when the reasoning is fresh. They rarely are, because writing them up feels like a separate task that requires sitting down and composing.

Keep a running notes document for each project. When you make a significant decision during a working session, take sixty seconds with VoiceInk and speak the decision and the reasoning into the document. You do not need to make it formal. Just say what you decided and why.

That unpolished note, made immediately, is worth ten times more than the structured ADR you never write three weeks later.

The Real Benefit

The documentation that gets written is always better than the documentation that does not get written. Dictation lowers the cost of writing it far enough that "I'll do it later" has less force.

If your team's docs are sparse, try speaking them instead of typing them for a month. The improvement will not be because the tool is magic. It will be because the friction dropped below the threshold where avoidance wins.