E75 - Cómo trabajar colaborativamente en documentación

Resumen

El episodio 75 de enCoders trata sobre cómo documentar proyectos de ciencia de datos de forma colaborativa. Los conductores sostienen que la documentación es uno de los cuatro pilares de un proyecto, junto con los datos, el ambiente de explotación y el control de versiones. Explican que casi nadie la hace "después" aunque todos digan que sí, y que sin priorización de los líderes tiende a no existir. Distinguen documentación de usuario y de mantenimiento, y recomiendan escribirla de lo macro a lo micro en archivos separados. Repasan herramientas (Markdown, Quarto, Confluence, Obsidian, Notion, LaTeX, Docusaurus y otras) y comparten una plantilla de proyecto tipo "canvas analítico". La conclusión principal es que el mayor desafío es la adherencia, no la herramienta: la documentación desactualizada es peor que no tenerla, y conviene una plantilla flexible que no se vuelva un obstáculo.

Capítulos

• 00:00
  IntroPresentan el episodio 75 sobre trabajo colaborativo en documentación, con foco en herramientas útiles y buenas prácticas basadas en su experiencia.
• 00:49
  La importancia de la documentaciónSin buena documentación el proyecto muere cuando otra persona debe tomarlo o pasarlo a producción. La documentación es uno de los cuatro puntos clave (datos, ambiente de explotación, control de versión, documentación). Cuentan la anécdota de una encuesta en un workshop donde el 100% admitió que dejaría la documentación para después y el 100% reconoció que nunca la haría. Los líderes deben priorizarla y a los analistas no les gusta redactar. Proponen una plantilla que la gente rellene.
• 08:52
  Tipos de documentación de proyectos. Documentación de usuario o técnica.Distinguen documentación de usuario y de mantenimiento; en proyectos de datos la división es a veces difusa, pero un dashboard entregado a una contraparte requiere ambas. Debaten texto frente a video (el texto es primordial, el video complementa en interfaces visuales). Destacan un buen README con instrucciones de instalación, incluso Docker.
• 16:29
  Pruebas unitariasLas pruebas unitarias son documentación útil pero poco usadas en ciencia de datos, por ser proyectos iterativos y exploratorios y porque cargar datasets hace lentos los tests. Describen validaciones simples como comprobar que una tabla exista o tenga un mínimo de registros. Revisan estructuras de informe de documentación técnica de software y proponen describir de lo macro a lo micro, con README general breve y documentación por sección.
• 23:16
  Herramientas útiles para documentarPresentan una lista de herramientas generada con ChatGPT, algunas conocidas y otras no probadas por ellos.
• 23:58
  Quarto NotebooksPermiten mezclar código y texto en un mismo lugar, útil cuando se necesita ambos.
• 24:37
  MarkdownTexto plano formateable y renderizable a HTML, es lo que se ve en páginas como un README de GitHub; lo consideran fundamental.
• 25:47
  Sphynx, Read the Docs, GitBookHerramientas que no han usado; un participante del chat usa Sphinx para generar HTML desde los docstrings de paquetes Python. Hablan de la documentación en ciencia de datos frente a desarrollo tradicional y de un compañero cuyo conocimiento de infraestructura estaba solo "en su cabeza". Comentan que los data scientists suelen programar peor que los data engineers.
• 36:46
  ConfluenceWiki del ecosistema Atlassian (Jira, Bitbucket) fácil de usar, editable en simultáneo y enlazable con tickets y commits. La usan sobre todo como base de conocimiento del equipo. Debaten Jira y la importancia del buscador global; comparan con Word o Google Docs. Un invitado recordó que le quitaban el acceso a Confluence por no usarlo.
• 45:56
  Logseq y ObsidianMuestran Obsidian con sus notas de webinars, organizadas en carpetas, con links y mapa de conexiones, como mini wiki personal; Logseq se menciona como posible reemplazo open source. Discuten que ninguna herramienta automática documenta bien el código por sí sola, aunque es mejor que nada.
• 48:00
  MemesSegmento de memes de la comunidad, incluyendo uno sobre un clasificador de manzanas y otros sobre "¿dónde está la documentación?". Mencionan que dirigirán un curso con proyectos para estudiantes y deberán pedir documentación y datos. Insisten en documentar desde la primera semana, por ejemplo el objetivo del proyecto.
• 53:58
  Google Docs / Google DrivePrefieren una wiki frente a un sistema de archivos con carpetas por la búsqueda global.
• 54:22
  LaTeXNo lo recomiendan en general, pero sí para proyectos muy técnicos o teóricos con muchas fórmulas, o de forma simplificada con Markdown/Quarto. Recomiendan Overleaf, con plantillas.
• 54:58
  DocusaurusNinguno lo ha usado; parece abierto y permite levantar un sitio con estructura de wiki y buen estilo.
• 55:29
  Wiki en generalMencionan Confluence, Obsidian y Logseq como formas de armar wikis.
• 55:44
  NotionMuy popular en la industria tecnológica y gratuito para uso personal, lo que baja la barrera de entrada.
• 57:57
  ExcalidrawPizarra colaborativa gratuita; un espectador la usa con un plugin y guarda el archivo `.excalidraw` en el proyecto. Recuerdan un episodio previo sobre pizarras y mencionan herramientas específicas para flujos de procesos.
• 01:00:02
  Desafíos de la documentación colaborativaEl reto central es la adherencia: que la gente lea y use la documentación. Para decidir estándares y herramientas, defienden que una persona decida tras escuchar opiniones ("método de la tiranía") y que luego el equipo acate. La documentación obsoleta es peor que no tener ninguna, hay que borrar y versionar. Convencer hacia arriba es lo más difícil, por lo que sugieren negociar plazos tras hitos. También sugieren documentar soluciones a problemas comunes (por ejemplo un fallo de VS Code con ciertas librerías de servidores) y alimentar un chatbot con la documentación limpia. Mencionan la anécdota de un proceso en un banco que se dejó de calcular sin que nadie reclamara.
• 01:13:53
  Template de proyecto y canvas analíticoDebaten el orden entre escribir primero el script o primero la documentación en Confluence, y concluyen que hay que tener ambos. Presentan una plantilla de README "canvas analítico" inspirada en el business model canvas, con recursos, pregunta y objetivo de negocio, métricas, entregable, criterios de éxito del MVP, potencial económico, involucrados, estado y estructura de carpetas. Advierten que la plantilla no debe volverse un obstáculo y que conviene revisar los artefactos en retrospectivas.
• 01:25:35
  CierreInsisten en que la adherencia es el mayor desafío y que es mejor documentación incompleta pero actualizada. Mencionan el "bus factor" y su base de conocimiento de cinco años en Confluence. Recuerdan Discord y YouTube; el tema fue propuesto por una oyente llamada Caro.

Palabras clave