Documentar código es una de las tareas más importantes y a la vez más descuidadas en el desarrollo de software. Sin importar si trabajas en frontend, backend o en equipos de datos como data engineers o data analysts, saber documentar tu código marca la diferencia entre un proyecto sostenible y uno que nadie puede continuar. La buena noticia es que hoy existen herramientas de inteligencia artificial que hacen este proceso mucho menos tedioso y más eficiente.
¿Por qué la documentación técnica es tan relevante en cualquier equipo?
La documentación no solo vive dentro del código donde se ejecuta. También debe estar en repositorios de documentación oficial como Notion o GitHub, donde otras personas del equipo puedan entender el proceso, continuarlo y mejorar la estructura tanto del código como de la documentación dentro de una organización [0:21].
El problema es que muchos desarrolladores no tienen el tiempo o las buenas prácticas para llevar todo a una documentación oficial. Esto genera una brecha enorme cuando alguien nuevo necesita entender un proceso o cuando un colaborador deja la organización. Aquí es donde las herramientas de IA entran como grandes aliadas.
¿Cómo funciona Notion AI para crear documentación técnica?
Notion es una herramienta ampliamente usada a nivel empresarial para llevar procesos, crear documentación de todo tipo y organizar información. Lo interesante es que Notion internamente tiene un motor de inteligencia artificial que ayuda en la creación de distintos tipos de documentación, incluida la técnica [1:05].
El flujo es sencillo:
- Agregas un bloque de código, por ejemplo un modelo DDL de bases de datos SQL.
- Seleccionas la opción Ask AI.
- Escribes instrucciones en lenguaje natural, como: "crea una documentación técnica como diccionario de datos y agrega descripciones de las columnas y las tablas".
- La IA genera documentación con formato markdown, entendiendo las relaciones del modelo, las tablas y los tipos de datos [1:35].
Un diccionario de datos es una referencia que describe cada columna de una tabla: su nombre, tipo de dato y una descripción de su propósito. La IA crea estas descripciones desde cero cuando el modelo original no las tiene. Algunas serán muy precisas, como que address es la dirección del cliente, y otras quizá necesiten un ajuste manual, pero el punto de partida ahorra muchísimo tiempo [2:15].
Este mismo enfoque se puede replicar con Python, Rust, JavaScript, PHP o cualquier lenguaje de programación y modelo de arquitectura técnica.
¿Cómo usar ChatGPT para documentar un script en Python?
ChatGPT también permite crear distintas etapas de documentación, tanto de código como documentación global. La clave está en el prompt que le proporcionas [3:10].
Un ejemplo de prompt efectivo sería: "Eres un experto en Python y en buenas prácticas de documentación de código. Te daré un script en Python y tienes que comentarlo y hacer una descripción de la función del script. Utiliza documentación técnica de alto nivel."
En la demostración se usó un script que:
- Importa la librería Tweepy para interactuar con la API de Twitter.
- Define claves de conexión a la API.
- Se autentica y recorre tuits usando un cursor con un límite de 50 resultados.
- Almacena los datos en una lista y los convierte a un data frame de Pandas [3:45].
ChatGPT devolvió el código con comentarios explicando cada sección y una descripción general de su propósito. Esa salida se puede copiar directamente a Notion, quedando el código documentado junto con su descripción en el repositorio oficial del equipo [5:00].
¿Qué más puedes hacer con IA además de documentar tu propio código?
Estas herramientas no solo sirven para documentar código propio. También son muy útiles para entender código escrito por otra persona dentro de tu organización [5:55]. Es común encontrarse con un script heredado que requiere mucho tiempo para descifrar su propósito o entender cada línea.
Los LLM (modelos de lenguaje de gran escala) como ChatGPT, Bard o Bing Chat tienen un contexto amplio de librerías, patrones de código y buenas prácticas, lo que les permite:
- Explicar qué hace cada sección de un código externo.
- Identificar cómo modificar una pieza específica.
- Sugerir optimizaciones para llevarlo al siguiente nivel [6:20].
La combinación de Notion AI para documentación integrada y LLMs como ChatGPT para análisis profundo del código ofrece un flujo de trabajo poderoso. Si aún no documentas tu código con estas herramientas, es un excelente momento para incorporarlas a tu rutina diaria. ¿Ya usas alguna de estas herramientas para documentar? Comparte tu experiencia.
