Escribe descripciones de pull requests claras con dictado por voz

El cambio está listo, pero la descripción de la pull request todavía dice «actualizar documentación». Recuerdas por qué lo hiciste, qué detalle necesita una segunda opinión y qué has comprobado. Aun así, escribir todo ese contexto parece una tarea nueva.

El dictado por voz te permite empezar explicando el cambio como si tuvieras a un compañero al lado. Después puedes convertir la transcripción en un texto fácil de consultar. La guía de revisión de GitHub también destaca la importancia del contexto. Este proceso te ayuda a preparar el borrador con tus propias palabras.

1. Habla con los cambios a la vista

En tu Mac, abre los archivos modificados junto a un documento de notas o al formulario de la PR. Lee primero las diferencias reales. Describe lo que incluye esta solicitud, no todo lo que pensabas hacer durante el día.

Empieza con una frase sobre el resultado: «Este cambio añade una lista de preparación a la guía de contribución». Deja los nombres exactos de archivos, los números de incidencias y los comandos para la edición. Copiarlos suele ser más sencillo que deletrearlos.

2. Responde a cinco preguntas breves

Dicta en bloques pequeños y haz una pausa entre estos puntos:

• ¿Qué ha cambiado? Explica el resultado, no cada paso de edición.
• ¿Por qué hace falta? Describe el problema o la información que faltaba.
• ¿Por dónde conviene revisar? Señala la parte que merece atención.
• ¿Qué he comprobado? Indica las comprobaciones realizadas y sus resultados reales.
• ¿Qué queda pendiente? Separa dudas, casos sin verificar y trabajo fuera del alcance de esta PR.

Si el repositorio ya tiene una plantilla, utiliza sus apartados. El dictado sirve para completar el borrador, no para cambiar el formato del equipo.

3. Convierte la explicación en una guía para revisar

Este ejemplo ficticio trata de un cambio en documentación; no describe funciones de TypeFree:

He añadido una lista de preparación porque la guía daba por hecho que el entorno ya estaba listo. Empezad por la sección de requisitos previos. Abrí los enlaces en la vista previa y llevan a las páginas correctas, pero no he seguido todo el proceso en un equipo recién preparado. Me gustaría que alguien comprobara si falta algún requisito. Los comandos de instalación no han cambiado.

Tras editarlo, podría quedar así:

Resumen: Añadir una lista de preparación a la guía de contribución. Los comandos de instalación no cambian.

Motivo: Explicar qué deben preparar las personas que contribuyen por primera vez.

Foco de la revisión: Buscar pasos ausentes en la sección de requisitos previos.

Comprobaciones realizadas: Abrir cada enlace de la lista desde la vista previa de la documentación; todos llevan a su destino previsto.

Sin comprobar: Completar todo el proceso de configuración en un equipo con un entorno limpio.

Es un ejemplo de redacción, no un informe de pruebas que puedas reutilizar sin cambios. Sustituye cada comprobación por tus propios resultados. «Voy a probarlo» pertenece al trabajo pendiente, no a la validación terminada.

4. Revisa los detalles que requieren precisión

Copia los nombres de archivos y los enlaces desde su origen y confirma que correspondan a este cambio. Presta atención al significado: «comandos modificados» y «comandos no modificados» describen alcances opuestos.

Elimina la historia de cada intento, salvo que explique una decisión importante. Quien revisa necesita entender el motivo de la solución final, no leer la transcripción de toda tu tarde. Mantén visibles las dudas en lugar de convertirlas en afirmaciones tajantes.

5. Termina con una petición concreta

En vez de «¿Alguna opinión?», pregunta «¿Esta lista incluye todos los requisitos que necesita alguien que contribuye por primera vez?». Antes de compartirla, contrasta la descripción con los archivos modificados y los resultados de las comprobaciones.

Para otras tareas, consulta las guías sobre informes de errores claros y borradores de documentación por voz.

TypeFree es una forma sencilla de convertir lo que dices en texto editable y escribir más rápido. Pruébalo en tu próxima descripción de PR: explica el cambio, añade referencias exactas y revisa el texto antes de publicarlo.