Ganancias:
- Capacidad para producir borradores README, docstring y changelog basados en el público objetivo y la fuente con IA
- Capacidad de separar las capas "qué/cómo" y "por qué" en la documentación y agregar el "por qué" como humano
- Verificar los pasos de instalación ejecutándolos personalmente y haciendo que el documento forme parte del cambio de código.
La parte del software que más frecuentemente se descuida pero que dura más es la documentación. El código es legible incluso después de meses; La persona que lo escribió se ha ido, el contexto se olvida y sólo queda lo que estaba escrito. Un buen README (documento introductorio que explica qué es un proyecto y cómo instalarlo y ejecutarlo), comentarios de código explicativos y una documentación API actualizada (una referencia que explica cómo usar una interfaz) determina directamente la velocidad de un equipo. La IA elimina gran parte de la “fatiga de la escritura” de la documentación, pero tiene una trampa: la IA puede inferir del código lo que hace, pero a menudo no puede saber por qué se hace de esa manera.
En esta unidad, aprenderá cómo producir README, comentario de código, cadena de documentación (bloque de comentarios escrito por función/clase), documento API y registro de cambios con IA; y cómo preservar humanamente la parte más valiosa de la documentación: el “por qué”.
Distinción entre "qué" y "por qué"
Hay dos capas de documentación. El primero es qué/cómo: "esta función ordena una lista", "ejecute este comando para instalar". Estos se pueden extraer del código y la estructura; La IA sobresale aquí. En segundo lugar, por qué: "por qué hicimos este servicio asíncrono en lugar de síncrono", "por qué este valor límite es de 30 segundos", "por qué elegimos esta biblioteca sobre la otra". Estos no están escritos en el código; Es producto de decisiones de diseño, limitaciones y dolores del pasado.
La IA no sabe "por qué"; En el mejor de los casos, constituye una suposición razonable, lo cual es peligroso, porque una razón equivocada es peor que ninguna razón. Así que la división del trabajo es clara: la IA redacta el “qué/cómo” y tú añades el “por qué”. El comentario más valioso es el que dice lo que el código no puede decir.
Consejo: No repita con un comentario lo que dice claramente el código en sí (como i = i + 1 // aumentar i en uno). La IA a veces produce comentarios redundantes; Elimínalos y dedica tu energía a los comentarios de "por qué".
Paso a paso: Generación de documentación con IA
- Especifique el público objetivo. "Un desarrollador que recién comienza", "el equipo externo que utilizará esta API", "el futuro yo": la audiencia marca el tono del lenguaje y la profundidad.
- Da la fuente. Agregue el código relevante, el archivo README existente y el uso de ejemplo al mensaje. Un documento sin fuente es una invitación a la fabricación.
- Estructura de imposición. Secciones estándar para README (Propósito, Instalación, Uso, Configuración, Contribución), formato de proyecto para cadena de documentación.
- Marque los espacios del "por qué". Pídale a la IA que marque las decisiones cuya justificación desconoce como "aquí se requiere una nota de 'por qué'"; Luego llena esos espacios en blanco.
- Verificar. Ejecute realmente los pasos de instalación; prueba el código de muestra. Un archivo README que no funciona es peor que ningún archivo README.
Tres mini estuches
Caso 1: Incorporación acelerada del archivo README. Faltaba el archivo README de una herramienta de código abierto; Los nuevos contribuyentes tuvieron problemas con la instalación durante una media de 2 horas. El equipo entregó los scripts de instalación y el paquete.json a AI y redactó un archivo README estructurado, luego ejecutó los pasos ellos mismos en una máquina limpia y agregó las dos dependencias que faltaban. El tiempo de instalación para los contribuyentes posteriores se redujo a un promedio de 25 minutos.
Caso 2: La trampa inventada del “por qué”. Un desarrollador pidió a la IA un comentario junto a un valor de tiempo de espera (tiempo de espera = 30). La IA escribió una justificación razonable pero incorrecta para "tolerar una alta latencia de la red"; la verdadera razón fue el límite contractual de 30 segundos de un servicio posterior. La mala interpretación llevó a un desarrollador posterior a aumentar innecesariamente el valor, lo que provocó un incidente. Lección: el propietario del código debe verificar la justificación.
Caso 3: el estándar Docstring se ha automatizado. Un módulo auxiliar con 40 funciones no tenía cadenas de documentación. A la IA se le dio el formato del proyecto (estilo Google) y produjo descripciones de parámetros, retornos y excepciones para cada función; El desarrollador los revisó y corrigió algunas declaraciones de tipos incorrectas. Documentar 40 funciones se redujo de aproximadamente medio día a una hora.
Cuatro plantillas copiables
Borrador README estructurado:
Público objetivo: {{p.ej. nuevo colaborador}}.Escriba un borrador README basado en los archivos a continuación. Secciones: Propósito, Características, Requisitos, Instalación, Operación, Configuración, Pruebas, Aporte. Extraiga los comandos de instalación/ejecución de archivos reales; ADECUADO. Marque los lugares de los que no esté seguro con "[VERIFICAR]". Fuente: {{paquete.json/scripts/código de muestra}}
Referencia de cadena de documentación/API:
Escriba una cadena de documentación para estas funciones en formato {{estilo de proyecto: Google/NumPy/JSDoc}}: breve resumen, parámetros (tipo + significado), retorno, excepciones lanzadas, 1 breve ejemplo. No repita lo que dice CLARAMENTE el código. Marque las decisiones de diseño que requieren "por qué" como "[POR QUÉ ES NECESARIO]", no escriba una justificación inventada.{{code}}
Eliminar espacios para el comentario "por qué":
En este código, el próximo desarrollador podría preguntar "¿por qué es así?" (números mágicos, decisiones inusuales, soluciones alternativas). Dé un comentario ESQUELETO para cada uno, pero deje el fundamento EN BLANCO; Completaré la justificación.{{code}}
Registro de cambios/declaración de relaciones públicas:
Escriba una {{entrada de registro de cambios / descripción de relaciones públicas}} de la diferencia a continuación. Formato: Qué cambió (en el idioma del usuario), Por qué (problema: {{...}}), Cambio importante (si corresponde), ¿Se ha probado? Ajuste la jerga técnica al público objetivo.{{diff}}
Aviso débil / Aviso fuerte
Débil: "Escribe un archivo README para este proyecto".
Fuerte: "Público objetivo: un desarrollador que clona este repositorio por primera vez. Según el paquete.json, docker-compose.yml y la carpeta scripts/ adjuntos, escriba un borrador README con las secciones Propósito, Requisitos, Instalación, Operación, Pruebas y Contribución. Extraiga los comandos de estos archivos, no los invente; marque cualquier lugar donde no esté seguro con [VERIFICAR]".
La versión fuerte proporciona la audiencia, la fuente, la estructura y la regla de “hazlo, márcalo”; para que el documento esté basado en archivos reales y los lugares a verificar sean claramente visibles.
Tipo de documento
La IA funciona bien
Humano agrega/verifica
Instalación LÉAME
esquema de pasos
Ejecute los pasos y confirme.
Cadena de documentos/API
Estructura, parámetro, tipo.
Tipo correcto y "por qué"
Comentario de código
Resumen de "lo que está haciendo"
"¿Por qué es esta" justificación?
Registro de cambios/PR
primer borrador
Impacto y precisión
Decisión arquitectónica (ADR)
esqueleto
Decisiones y compromisos reales
La documentación requiere mantenimiento
El aspecto más peligroso de un documento es cuando parece verdadero aunque sea falso. Cuando el código cambia y el documento no se actualiza, se engaña activamente al lector. La IA facilita la actualización: emita una diferencia y pregunte "¿a qué partes del documento afecta este cambio?" puedes preguntar. Pero es el proceso el que garantiza la actualización: hacer que la actualización de la documentación forme parte del cambio de código (criterio de aceptación de PR). La IA se acelera; El equipo construye disciplina.
Precaución: No publique sin verificar los pasos de instalación en un archivo README. Un documento de "probablemente trabajo" puede arruinar el primer día de un nuevo desarrollador y erosionar la confianza. Ejecute los pasos usted mismo en un ambiente limpio.
Errores comunes
- Conseguir que el “por qué” se ajuste a la IA. La falsa justificación es peor que ninguna justificación; El propietario del código debe escribir el motivo del diseño.
- No verificar los pasos de instalación. README que no funciona destruye la confianza.
- Comentario innecesario repitiendo el código. Produce ruido, oscureciendo las interpretaciones reales del "por qué".
- Sin especificar el público objetivo. Un documento que no está claro para quién está escrito no es de utilidad ni para el principiante ni para el experto.
- Separando la actualización del proceso. Si el documento no se actualiza con el código rápidamente se vuelve engañoso.
En resumen
La IA elimina gran parte de la carga mecánica de la documentación: borradores rápidos README, cadena de documentos, referencia de API, registro de cambios y descripciones de relaciones públicas. Pero no puede saber el "por qué", cuál es la capa más valiosa, y es peligroso inventarla. La división del trabajo es clara: la IA produce el “qué/cómo”, y tú añades el “por qué”. Especifique la audiencia, proporcione recursos, imponga estructura, marque lugares para encajar y verifique cada paso de la instalación ejecutándolo usted mismo. Haga que la documentación sea una parte integral del cambio de código.
Tarea de aplicación
Elija un módulo o proyecto pequeño cuya documentación falte o esté desactualizada. Primero genere un esquema a partir de AI con la plantilla de “borrador README estructurado” (o cadena de documentación); Asegúrese de proporcionar la fuente y el público objetivo. Luego, revise cada punto donde la IA haya marcado [VERIFICAR] o [POR QUÉ ES NECESARIO]: ejecute los pasos de configuración y complete los "por qué" del diseño con su propio conocimiento. Tenga en cuenta cuántos pasos deben corregirse y cuántos "por qué" agregó.
lista de verificación
- [] En la documentación, distingo las capas "qué/cómo" y "por qué".
- [ ] No hago que la IA invente el "por qué", lo agrego yo mismo.
- [] Le doy al mensaje la audiencia objetivo y los archivos fuente reales.
- [ ] Verifico los puntos [VERIFICAR] marcados por la IA ejecutándolos personalmente.
- [ ] Elimino comentarios innecesarios que repiten el código.
- [] Estoy haciendo que la actualización de la documentación sea parte del cambio de código.