Dictating Code Comments and Docs: A Developer's Honest Take

Ask most developers what part of their job they procrastinate on most, and documentation lands near the top of every honest answer. It is not that the knowledge is not there. It is that translating what you just built into clear prose, while your hands are already tired from six hours of coding, feels like a second job that nobody formally assigned.

Voice dictation does not write your docs for you. But it removes enough of the friction that the work actually gets done.

Where Voice Fits in a Dev Workflow

Dictation is not useful for writing code itself. Syntax is too precise, variable names are too arbitrary, and the back-and-forth of actual programming happens in a rhythm that voice cannot match. Trying to dictate a function is an exercise in frustration.

But most of what surrounds code is plain prose. Inline comments explaining why a decision was made. README files walking through setup and usage. Pull request descriptions summarizing what changed and what to watch for. Confluence pages, Notion docs, Slack summaries, ticket descriptions. This is where voice earns its place.

The Comment Problem

Good inline comments explain intent, not mechanics. A comment that says "increments counter" next to a line that increments a counter is noise. A comment that says why the counter exists, what edge case it handles, and what happens if it exceeds a threshold, that is useful.

Writing that kind of comment while typing feels like context-switching. You just wrote the code; now you have to shift into documentation mode and produce a paragraph. Many developers skip it entirely.

With a tool like VoiceInk running on your Mac, you can keep your hands on the keyboard, finish writing a function, then hit a key and speak the comment before you lose the mental context. It takes fifteen seconds. The comment is there. You move on.

PR Descriptions That People Actually Read

Pull request descriptions are often terrible because writing them happens at the worst possible time, right when you are ready to stop thinking about the problem and move on.

Dictating a PR description takes about two minutes if you do it while the work is still fresh. You speak to the reviewer like you are explaining it in a standup: what the problem was, what you changed, what you decided not to change and why, and where they should focus their attention.

This kind of description is more useful than a bulleted list of file changes, and it is faster to produce by talking than by typing.

Capturing Decisions Before They Evaporate

Architectural decisions are some of the most valuable things a team can document, and some of the least documented things in any codebase. By the time someone writes an ADR, the reasoning is half-remembered and the dissenting opinions are gone.

Voice makes it practical to capture decisions in the moment. After a technical discussion in Slack or a meeting, spend three minutes dictating a note: what was decided, what the alternatives were, and what factors drove the choice. Drop it into whatever system your team uses. Future engineers, including future you, will find it.

Setup Is Simple

On a Mac, VoiceInk runs locally with no audio leaving your machine. For developers working on proprietary or sensitive codebases, this matters. You are not sending architectural decisions or internal system details to a cloud service. You press a shortcut, speak, and the text appears in whatever window is active, your editor, your browser, your terminal notes.

No configuration per-app. No special integrations. It just works where your cursor is.

The Actual Benefit

Documentation debt compounds. Every undocumented function, every unexplained decision, every PR with a one-line description becomes a future tax on everyone who touches that code.

Voice dictation does not make documentation glamorous. It just makes the excuse of "too much friction" a little harder to justify. Try speaking your next PR description instead of typing it.