Documentar código sigue siendo una de las tareas más subestimadas y, al mismo tiempo, más valiosas en cualquier equipo de desarrollo. Ya sea que trabajes en frontend, backend o equipos de datos, saber documentar correctamente marca la diferencia entre un proyecto sostenible y uno que nadie puede continuar. La buena noticia es que herramientas de inteligencia artificial como Notion AI y ChatGPT pueden acelerar ese proceso de forma significativa.
¿Por qué la documentación técnica es esencial en cualquier equipo?
No importa el rol que desempeñes: data engineer, data analyst o desarrollador, la documentación permite que otras personas comprendan tu proceso, lo continúen y mejoren la estructura de código dentro de una organización [0:18]. No se trata solo de comentar líneas dentro del código fuente, sino también de mantener repositorios de documentación oficial en plataformas como Notion o GitHub.
El problema recurrente es que documentar resulta tedioso. Los desarrolladores muchas veces no cuentan con el tiempo o las buenas prácticas para llevar todo a una documentación formal [7:45]. Aquí es donde la inteligencia artificial se convierte en un gran aliado.
¿Cómo usar Notion AI para crear un diccionario de datos?
Notion es una herramienta ampliamente utilizada a nivel empresarial para gestionar procesos y documentación de cualquier tipo. Lo relevante es que Notion integra un motor de inteligencia artificial capaz de asistir en la creación de documentación técnica [1:12].
El flujo de trabajo es sencillo:
- Pegas 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" [2:02].
Notion AI genera automáticamente un diccionario de datos en formato markdown, con estructura de tabla que incluye el nombre de cada columna, su tipo de dato y una descripción generada desde cero [2:28]. Por ejemplo, para una tabla llamada customer, identifica columnas como address (dirección del cliente) o phone (número de teléfono del cliente). Algunas descripciones pueden necesitar ajustes manuales, pero el punto de partida ahorra horas de trabajo.
Este proceso no se limita a SQL. Puede replicarse con Python, Rust, JavaScript, PHP o cualquier lenguaje de programación [3:35].
¿Cómo documentar un script de Python con ChatGPT?
ChatGPT también permite crear distintas etapas de documentación, ya sea de código específico o documentación global [4:08]. La clave está en el prompt que utilices.
Un ejemplo efectivo de prompt 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" [4:18].
Al proporcionarle un script que usa la librería Tweepy para conectarse a la API de Twitter y almacenar tuits en un data frame de Pandas, ChatGPT devuelve el código comentado sección por sección [4:50]:
python
Importamos las bibliotecas necesarias
import tweepy # Interacción con la API de Twitter
import pandas as pd # Manejo de datos
Configuración de claves API
Autenticación con las claves
Creación de instancia de la API
Lista vacía para almacenar datos de tuits
Cursor de Twitter para recorrer tuits con límite de 50
Recopilación de datos específicos de cada tuit
Conversión a DataFrame de Pandas
Cada bloque incluye una explicación clara de su propósito [5:30]. Además, ChatGPT genera una descripción general de lo que hace el script, lista para copiar directamente a Notion junto con el código documentado [6:48].
¿Para qué más sirve la IA en documentación de código?
Estas herramientas no solo documentan código propio. También resultan muy útiles para entender código escrito por otra persona [8:20]. Es común encontrarse con scripts heredados donde falta contexto sobre su propósito o sobre qué hace cada línea.
Los modelos de lenguaje grande (LLM) como ChatGPT, Bard o Bing Chat tienen un contexto amplio de librerías y patrones de código que les permite interpretar, explicar y hasta optimizar piezas de código externo [8:50].
Las posibilidades concretas incluyen:
- Generar diccionarios de datos desde modelos DDL.
- Comentar scripts en cualquier lenguaje de programación.
- Crear descripciones funcionales para repositorios de documentación.
- Comprender y explicar código de otros colaboradores.
Si en tu equipo la documentación es una deuda pendiente, probar estas herramientas puede ser el primer paso para transformar esa realidad. ¿Ya las has usado en tu flujo de trabajo? Comparte tu experiencia.
