Un issue útil de GitHub se escribe mejor mientras el fallo sigue en pantalla. La secuencia exacta está fresca. La línea extraña de la consola sigue visible. Recuerdas qué solución provisional falló y qué cambió después de la última versión.
Entonces abres el editor y el informe queda reducido a: «El inicio de sesión falla en Safari».
El dictado por voz ayuda con esa pérdida concreta. No vuelve precisa una observación vaga por sí solo. Permite conservar con menos esfuerzo la evidencia, el orden y los límites que ya conoces antes de comprimirlos en un título y una frase.
Los issues de GitHub sirven para seguir errores, mejoras, tareas y otra información del proyecto. El cuerpo usa GitHub Flavored Markdown, con títulos, listas de tareas, enlaces y bloques de código. No es solo un mensaje: es un pequeño registro de trabajo que otra persona debe poder revisar, reproducir y cerrar.
Deja la estructura fija en la plantilla y dicta los hechos variables
Muchos equipos ya conocen los apartados que necesitan:
- Resumen
- Pasos para reproducir
- Resultado esperado
- Resultado real
- Entorno
- Criterios de aceptación
Escribir esas etiquetas no es lo costoso. Lo costoso es reconstruir qué ocurrió debajo de cada una.
Una división práctica consiste en guardar una plantilla Markdown en el repositorio y dictar dentro de ella la evidencia que cambia. GitHub admite plantillas Markdown y formularios de issues, de modo que las preguntas estables pueden aparecer al abrir el editor. La voz aporta los hechos de hoy: el cuarto clic, la versión del navegador, el token antiguo, la pantalla que apareció y la prueba que debe pasar cuando se corrija el fallo.
La plantilla también evita que el dictado se convierta en un informe largo sin forma. La estructura queda escrita; la grabación rellena los huecos.
Los pasos de reproducción necesitan orden y un punto de ruptura
«La carga falla a veces» deja demasiadas preguntas. ¿Qué archivo? ¿Qué ruta? ¿Antes o después de iniciar sesión? ¿Reintentar ayuda? ¿Qué se ve cuando falla?
Dicta los pasos en orden y marca dónde se separa el comportamiento observado del esperado:
- Empieza desde un estado conocido.
- Nombra la acción que realizas.
- Di qué aparece después de cada acción importante.
- Detente en el primer resultado incorrecto.
- Añade si el fallo se repite.
Por ejemplo:
Empieza con una cuenta con sesión iniciada y sin imagen de perfil. Abre Configuración, elige un PNG de más de cinco megabytes y pulsa Guardar una vez. La barra llega al cien por cien y luego vuelve al avatar anterior sin mostrar ningún error. Al recargar, la imagen nueva no aparece. Si repites el proceso con un PNG más pequeño, funciona.
Ese párrafo incluye un caso de comparación, un resultado visible y una comprobación de repetibilidad. Son detalles que suelen desaparecer cuando el informe se escribe con prisa.
Separa lo observado de la explicación
Un issue se vuelve más difícil de investigar cuando una suposición se presenta como si fuera una prueba.
«La invalidación de caché está rota» puede ser correcto, pero es un diagnóstico. «La segunda petición devuelve la URL antigua del avatar después de que el endpoint de carga responda 200» es una observación. La segunda frase da algo verificable aunque la causa final esté en otro lugar.
Al dictar, marca los límites:
- «Observé…» para el comportamiento visible.
- «Esperaba…» para el contrato en el que te apoyabas.
- «Mi hipótesis actual…» para una explicación provisional.
- «No he verificado…» para una pregunta abierta.
Hablar facilita incluir una teoría porque estás explicando el problema como lo entiendes. Nombrarla como teoría mantiene útil el issue si luego resulta equivocada.
Escribe los tokens exactos y dicta qué demuestran
La voz funciona bien para la cronología y el razonamiento. Funciona peor cuando cada carácter importa.
Usa el teclado para:
- hashes de commit y números de issue
- rutas de archivo e identificadores
- URL con parámetros de consulta
- comandos de shell y expresiones regulares
- trazas y fragmentos de registro
- versiones que se diferencian por un dígito
Pega los registros y el código dentro de bloques delimitados, en lugar de leerlos en voz alta. GitHub renderiza esos bloques y puede aplicar resaltado de sintaxis cuando indicas el lenguaje. Un fragmento breve suele ser más útil que una paráfrasis hablada porque los espacios, los signos y el orden de las líneas pueden contener la prueba.
Después dicta la frase que rodea al token exacto: de dónde salió el registro, qué acción lo produjo y qué línea importa. El teclado conserva el artefacto. La voz conserva su significado.
Los criterios de aceptación crean una línea de llegada
Un issue puede describir bien el fallo y seguir siendo difícil de cerrar. «Arreglar la carga del avatar» no aclara si basta con mostrar un error, aceptar archivos mayores, reintentar la petición o actualizar la imagen de inmediato.
Añade criterios que puedan comprobarse tras el cambio. Las listas de tareas de GitHub usan casillas Markdown, por lo que los resultados permanecen visibles durante el trabajo.
Para el ejemplo anterior:
- Una imagen compatible muestra el avatar nuevo sin recarga manual.
- Un tamaño no compatible produce un error visible.
- Una carga fallida no sustituye el avatar existente.
- La prueba de regresión cubre el límite de tamaño que fallaba.
Dictarlos suele ser más fácil que escribirlos porque puedes responder a una pregunta directa: «¿Qué tendría que ver para aceptar que está corregido?». La lista debe describir resultados, no imponer una implementación salvo que esa implementación sea el requisito.
Clean conserva el informe; Raw conserva toda la toma
TalkTalkType graba mientras mantienes pulsado Option-Espacio y devuelve el resultado al campo que tenía el foco. En el editor de un issue, puedes seguir viendo el repositorio, la plantilla y los comentarios mientras hablas.
Clean realiza una limpieza ligera y fiel. Mantiene todas las palabras, su orden, tu registro y la brevedad que pretendías. Solo elimina vacilaciones inequívocas y devuelve una línea. No convierte en silencio el informe en otra plantilla ni inventa datos que faltan.
Raw no aplica limpieza y conserva la transcripción completa, incluidos los comienzos fallidos. Es útil si vas a editar mucho o si hay un nombre propio poco común que cualquier limpieza podría alterar.
Ningún modo hace seguro dictar texto técnico exacto. Revisa el borrador antes de enviarlo y sustituye versiones, nombres, rutas y cifras dudosas por valores copiados. Dictado que funciona en cualquier app de Mac explica la entrega al campo enfocado y la alternativa del portapapeles.
No dictes secretos en un campo cómodo
Un informe puede estar en un repositorio público, en uno privado de empresa o en un proyecto que más tarde se haga público. Trata el destino como parte del límite de datos.
No pronuncies claves API, cookies de sesión, tokens de acceso, datos privados de clientes ni credenciales de producción. Elimina también esos datos de los registros pegados. El dictado reduce el esfuerzo de entrada; no cambia quién podrá leer el issue resultante.
TalkTalkType no conserva audio, transcripciones en bruto ni texto limpio como historial del servidor, pero el texto final se envía a GitHub al crear el issue. Dictado privado en Mac sigue la grabación y la transcripción por las etapas anteriores.
Empieza por el issue que ibas a posponer
Abre la plantilla del repositorio mientras el fallo todavía se reproduce. Escribe el título y los identificadores exactos. Después dicta en una sola toma el estado inicial, las acciones ordenadas, el primer resultado incorrecto, la repetibilidad, el comportamiento esperado y la incertidumbre actual.
Léelo una vez. Pega el fragmento mínimo de registro que sirva. Añade una lista que defina cuándo termina el trabajo.
El objetivo no es escribir un issue más largo. Es conservar suficiente información del momento para que otra persona pueda actuar cuando ese momento ya haya pasado.