Escribe documentación de código con voz: comentarios, READMEs y docs que no apestan
Aprende cómo el dictado por voz hace más rápida la documentación de código. Comentarios, READMEs, docs de API y docstrings en minutos en vez de horas.
Resumen rápido: Los desarrolladores evitan escribir documentación porque les obliga a un cambio doloroso de código a prosa. El dictado por voz elimina esa fricción. Lees el código, luego dices la explicación. El resultado es mejor documentación escrita en una fracción del tiempo. Esta guía cubre flujos de trabajo para comentarios inline, docstrings, READMEs y documentación de API usando herramientas de programación por voz como Murmur.
Por qué los desarrolladores odian escribir documentación
Seamos honestos. La mayoría de los desarrolladores preferiría refactorizar un código legacy antes que escribir un README.
No es pereza. Es fricción. Escribir documentación requiere un modo de pensamiento fundamentalmente diferente al de escribir código. El código es preciso, estructurado y conciso. La documentación es explicativa, conversacional y extensa. Cambiar entre ambos es cognitivamente costoso.
Esto es lo que suele pasar:
- Terminas de construir una funcionalidad
- Sabes que deberías documentarla
- Abres el README o un archivo de documentación
- Te quedas mirando la página en blanco
- Escribes unas pocas frases a regañadientes
- Decides que "el código se documenta solo" y sigues adelante
El resultado son bases de código con READMEs desactualizados, docstrings faltantes y comentarios inline que dicen // TODO: add documentation here desde hace tres años.
El problema central no es la motivación. Es el método de entrada. Escribir lenguaje natural cuando tu cerebro está en modo código es lento y antinatural. Puedes pensar la explicación más rápido de lo que puedes escribirla. Y esa brecha entre la velocidad del pensamiento y la velocidad de escritura es donde muere la documentación.
La voz elimina el cuello de botella
Cuando le explicas código a un compañero, no te cuesta encontrar las palabras. Miras la función, entiendes lo que hace y lo dices en voz alta. La explicación fluye de forma natural porque el habla es el formato nativo para las explicaciones.
El dictado por voz trae ese mismo flujo a la escritura de documentación. En lugar de escribir prosa carácter por carácter, lees el código, pulsas un atajo y dices la explicación como si un desarrollador junior te acabara de preguntar "¿qué hace esto?"
La diferencia de velocidad es significativa. La mayoría de los desarrolladores escriben prosa a 40-60 palabras por minuto. Hablando cómodamente se llega a unas 130-150 palabras por minuto. Eso es aproximadamente 3 veces más rápido para exactamente el tipo de escritura que requiere la documentación.
Pero la velocidad es solo la mitad de la historia. La documentación dictada tiende a ser más completa y más natural. Cuando dices una explicación, incluyes contexto y matices que omitirías al escribir porque "no vale la pena el esfuerzo". Esos detalles extra son exactamente lo que hace útil la documentación.
Flujo de trabajo 1: Comentarios inline y anotaciones de código
Los comentarios inline son la documentación más simple de dictar. El flujo de trabajo es directo:
- Lee el bloque de código que quieres anotar
- Coloca tu cursor encima de la línea relevante
- Pulsa tu atajo de voz (Ctrl+Space en Murmur)
- Di la explicación
Por ejemplo, estás mirando esta función:
function reconcileInventory(orders, stockLevels) {
const adjustments = orders.reduce((acc, order) => {
const current = stockLevels.get(order.sku) ?? 0;
const delta = order.type === 'return' ? order.qty : -order.qty;
acc.set(order.sku, (acc.get(order.sku) ?? current) + delta);
return acc;
}, new Map());
return adjustments;
}En lugar de escribir un comentario, dices:
"Esta función toma un array de pedidos y un mapa de niveles de stock actuales, luego calcula el ajuste neto de inventario para cada SKU. Procesa los pedidos como ventas que disminuyen el stock y devoluciones que lo aumentan. El resultado es un mapa de SKU a nivel de stock ajustado."
Eso tomó unos ocho segundos en decirlo. Escribirlo habría tomado 30-40 segundos, y probablemente habrías escrito algo más corto y menos útil.
Consejos para mejores comentarios inline por voz
Empieza con el "por qué", no el "qué". El código ya muestra qué ocurre. Tu comentario por voz debería explicar por qué. Di "Verificamos null aquí porque la API legacy a veces devuelve null en lugar de un array vacío" en lugar de "Verificar si el valor es null".
Habla en frases completas. La transcripción moderna con IA funciona mejor con pensamientos completos. No pauses entre cada pocas palabras. Deja que el pensamiento fluya de forma natural y la puntuación seguirá.
No te preocupes por el formato en la primera pasada. Di la explicación, luego edita rápidamente el resultado con el teclado. Voz para el primer borrador, teclado para pulir. Este enfoque híbrido se cubre en nuestra guía completa de programación por voz.
Flujo de trabajo 2: Docstrings y documentación de funciones
Los docstrings son donde el dictado por voz realmente brilla. Un buen docstring explica qué hace una función, qué esperan sus parámetros, qué devuelve y qué puede fallar. Eso es mucho para escribir. Pero son solo unos 15 segundos hablando.
Así es el flujo de trabajo en VS Code:
- Coloca tu cursor dentro de la apertura del docstring (después de
"""en Python,/**en JavaScript/TypeScript) - Pulsa tu atajo de voz
- Describe la función como si la explicaras a alguien que nunca ha visto el código
Ejemplo en Python:
Ves esta función:
def sync_user_preferences(user_id: str, source: str = "api") -> dict:
...Dices:
"Sincroniza las preferencias del usuario desde la fuente especificada al caché local. Recibe un string con el ID de usuario y un parámetro opcional de fuente que por defecto es API. También puede aceptar webhook o migration como valores de fuente. Devuelve un diccionario que contiene las preferencias combinadas y un timestamp de la última sincronización. Lanza un UserNotFoundError si el ID de usuario no existe, y un SyncConflictError si las preferencias remotas y locales tienen timestamps divergentes."
Eso produce un docstring completo en 12 segundos. El tiempo equivalente escribiendo sería más de un minuto, y la mayoría de los desarrolladores se habrían detenido en "Sincroniza las preferencias del usuario".
Ejemplo en TypeScript/JSDoc:
Para una función TypeScript, el mismo enfoque funciona. Coloca tu cursor dentro del bloque JSDoc y di:
"Valida y normaliza un payload de webhook entrante de Stripe. Verifica la firma del webhook contra el secreto configurado, parsea el tipo de evento y devuelve un objeto de evento normalizado. Lanza un InvalidSignatureError si la firma no coincide. El parámetro timeout controla cuánto tiempo esperar para la verificación de la firma y por defecto es 5000 milisegundos."
Documentar código existente en lote
Uno de los mejores usos del dictado por voz es hacer sprints de documentación en bases de código existentes. El flujo de trabajo:
- Abre un archivo con funciones sin documentar
- Lee la primera función
- Dicta el docstring
- Pasa a la siguiente función
- Repite
Puedes documentar un módulo entero en 15-20 minutos que habrían tomado una hora o más escribiendo. La clave es que ya entiendes el código. El cuello de botella siempre fue la escritura, no el pensamiento.
Flujo de trabajo 3: Archivos README
Los archivos README son la puerta de entrada de cada proyecto. También son el artefacto de documentación más descuidado en la mayoría de las bases de código. El dictado por voz cambia la economía de escribirlos.
El proceso README con voz primero
En lugar de quedarte mirando un archivo vacío, abre tu README y di cada sección:
Descripción del proyecto:
"Esta es una biblioteca de middleware para Express.js que maneja rate limiting con almacenamiento respaldado por Redis. Soporta tanto algoritmos de ventana fija como de ventana deslizante, límites configurables por ruta e identificación automática de clientes basada en IP y en API key. Diseñada para uso en producción con soporte integrado para clustering y escalado horizontal."
Sección de instalación:
"Instala usando npm install at rate limiter middleware. Requiere Node 18 o superior y una instancia de Redis en ejecución. Para la configuración por defecto, no se necesita configuración adicional. Para configuraciones personalizadas, consulta la sección de configuración a continuación."
Sección de uso:
Di un ejemplo de uso como si estuvieras guiando a un compañero:
"Importa el rate limiter del paquete. Crea una nueva instancia pasando la URL de conexión a Redis. Luego úsalo como middleware de Express con app.use. Puedes pasar un objeto de opciones para configurar el tamaño de la ventana, las peticiones máximas y el algoritmo. Aquí tienes un ejemplo básico..."
Luego añade el bloque de código con tu teclado. Este enfoque híbrido (voz para prosa, teclado para código) es la forma más eficiente de escribir documentación técnica.
Consejos para README con dictado por voz
Dicta la prosa, escribe el código. Los bloques de código necesitan la precisión que el teclado maneja mejor. Pero todo el texto explicativo alrededor de esos bloques es perfecto para la voz.
Habla dirigiéndote a una persona. Imagina a un desarrollador que acaba de encontrar tu proyecto en GitHub. ¿Qué necesita saber primero? Háblale a esa persona.
Usa los encabezados como guía. Crea la estructura de encabezados primero (## Instalación, ## Uso, ## Configuración), luego rellena cada sección por voz. Los encabezados te dan un marco para que no tengas que pensar qué decir a continuación.
¿Listo para probar el dictado por voz?
Prueba Murmur gratis durante 7 dias con todas las funciones Pro. Dicta en cualquier app.
Descargar gratisFlujo de trabajo 4: Documentación de API
La documentación de API es repetitiva y extensa, lo que la hace ideal para el dictado por voz. Cada endpoint necesita una descripción, parámetros, ejemplos de request/response y códigos de error. Eso es mucho para escribir, pero el patrón es predecible.
Dictando descripciones de endpoints
Para cada endpoint de API, di estos elementos:
"POST slash API slash users. Crea una nueva cuenta de usuario. Requiere un body JSON con email, password y un display name opcional. El email debe ser único en todas las cuentas. La contraseña debe tener al menos 8 caracteres con una letra mayúscula y un número. Devuelve un 201 con el objeto de usuario creado incluyendo el ID de usuario generado y un timestamp. Devuelve 409 si el email ya existe. Devuelve 422 si el body de la petición no pasa la validación."
Eso describe el endpoint de forma más completa de lo que la mayoría de los desarrolladores escribirían, y tomó unos 15 segundos.
Dictando descripciones de esquemas
La documentación de modelos de datos se beneficia del mismo enfoque:
"El objeto user contiene un ID que es un UUID v4 generado en la creación, un email que es único y case-insensitive, un display name que por defecto es la parte del email antes del arroba, un timestamp created at en formato ISO 8601 y un campo status que puede ser active, suspended o deleted."
Consejos para dictar contenido técnico
Manejo de abreviaturas y términos técnicos
Las herramientas de transcripción impulsadas por IA como Murmur manejan correctamente la mayoría del vocabulario técnico porque usan el contexto para entender la intención. Sin embargo, algunos consejos ayudan con casos especiales:
Di los acrónimos de forma natural. "API", "JSON", "REST", "JWT" se reconocen cuando se dicen como acrónimos. No necesitas deletrearlos.
Usa contexto para términos ambiguos. Si dices "route handler para el endpoint de users", la transcripción entiende "route" en un contexto de programación. Hablar en frases completas proporciona el contexto que hace precisa la transcripción.
Deletrea nombres inusuales cuando sea necesario. Para términos propietarios o nombres de bibliotecas inusuales, puede que necesites deletrear una vez y luego corregir. Después de la primera ocurrencia, el motor de transcripción con IA a menudo detecta el patrón.
Puntuación y formato
La transcripción moderna con IA maneja bien la puntuación cuando hablas de forma natural. Algunos detalles específicos:
- Puntos y comas se insertan automáticamente basándose en tus patrones de habla
- Términos de código como nombres de funciones se pueden decir de forma natural y luego formatear con backticks usando el teclado
- Listas funcionan bien cuando las señalas verbalmente: "Primero... Segundo... Tercero..." La transcripción normalmente capta la estructura
El enfoque híbrido
El flujo de trabajo de documentación más productivo combina voz y teclado:
- Voz para toda la prosa explicativa, descripciones y contenido en lenguaje natural
- Teclado para bloques de código, formato (encabezados, negrita, enlaces) y ediciones precisas
- Voz de nuevo para revisar tu borrador. Léelo y dicta correcciones o adiciones
Este enfoque aprovecha las fortalezas de cada método de entrada. No luchas con el teclado para prosa extensa, y no luchas con la voz para formato preciso.
Dónde encaja Murmur
Murmur está diseñado exactamente para este flujo de trabajo. Funciona dentro de cualquier aplicación en tu PC, lo que significa que puedes dictar documentación en:
- VS Code directamente en tus archivos fuente
- Editores de terminal como Vim o Nano
- Herramientas basadas en navegador como el editor web de GitHub, Notion o Confluence
- Claude Code para hacer prompts a la IA para generar o mejorar documentación
Un atajo de teclado activa el dictado. Di tu documentación. El texto aparece donde está tu cursor. Sin cambiar de app, sin copiar y pegar, sin cambios de modo.
Con 5 dictados gratis por día más 7 días de prueba Pro o €39,97 por una licencia Pro de por vida, el costo de tener mejor documentación es insignificante. Compara eso con el costo de incorporar a un nuevo desarrollador que pasa tres días descifrando una base de código sin documentar.
El hábito de documentar
La mayor barrera para buena documentación no son las herramientas. Es el hábito. El dictado por voz reduce el esfuerzo lo suficiente como para hacer de la documentación una parte realista de tu flujo de trabajo diario en lugar de un remordimiento trimestral.
Aquí tienes un hábito simple para construir:
- Cada vez que termines una función, dedica 10 segundos a dictar un docstring
- Cada vez que cierres un PR, dedica 30 segundos a dictar un comentario resumen
- Cada viernes, dedica 10 minutos a dictar actualizaciones del README de tu proyecto
Diez segundos por función. Eso es todo lo que toma cuando puedes hablar en lugar de escribir. Y el efecto acumulativo de esas inversiones de 10 segundos es una base de código que los nuevos desarrolladores realmente pueden entender.
Cómo empezar
- Descarga Murmur (gratis, configuración de 2 minutos)
- Abre un archivo con código sin documentar
- Coloca tu cursor encima de una función
- Pulsa Ctrl+Space y explica qué hace la función
- Repite para la siguiente función
Empieza con un archivo. Documenta cada función por voz. Cronométrate. Te sorprenderá lo rápido que va cuando el cuello de botella es pensar, no escribir.
Tu base de código merece documentación que no apeste. Tu voz puede proporcionarla.
Lectura adicional
¿Listo para probar el dictado por voz?
Prueba Murmur gratis durante 7 dias con todas las funciones Pro. Dicta en cualquier app.
Descargar gratisRelated Articles
voice coding
Programación por voz con Claude Code: dicta tus prompts
Usa dictado por voz con Claude Code para escribir mejores prompts más rápido. Configuración paso a paso y ejemplos reales incluidos.
voice coding
Programación por voz en 2026: la guía completa
Todo lo que necesitas saber sobre programación por voz en 2026. Herramientas, configuración, consejos y flujos de trabajo para programar más rápido con tu voz.
voice coding
Cómo tripliqué mi velocidad de programación usando voz en Cursor
La experiencia real de un desarrollador usando escritura por voz en Cursor IDE. Aprende los flujos de trabajo que triplicaron la productividad al programar.