Problemas sobre documentación

Esta breve nota surge por comentarios que me hicieron en los espacios de networking el pasado 18 de noviembre durante la WebConf Latam 2022 (https://webconf.tech/).

Durante mi charla en la conferencia, entre otras cosas, introduje el concepto de Documinding, hablando de documentación ágil y de los problemas que plantea.

Mi sorpresa fue que luego recibí varias preguntas relacionadas al tema documentación en general:

1. ¿Cómo documentar un producto que tiene un core compartido entre varias instalaciones, pero luego una parte de la doc depende de la configuración de la instancia?
2. ¿Cómo convencer a un PM/gerente que es necesario asignar tiempo para documentar durante el desarrollo?
3. ¿En serio puedo hacer diagramas escribiendo una representación del mismo en un DSL que puede ser versionado con mi código?

La pregunta 1 no encontré una forma de responderla (quien me lo preguntó usaba Notion). ==#TODO== buscar respuesta a esto porque es un tema interesante.

La respuesta a la pregunta 2 va por el lado de traducir en dinero costos:

• costo de onboarding y hand-holding de nuevos devs.
• costo que tiene la falta de una visión única de lo que estamos construyendo
• costo de tener que generar dicha doc al momento de vender el producto

La respuesta de la pregunta 3 la di citando el thread de Twitter sobre just enough documentation y las herramientas que permiten documentar utilizando DSLs (conocidas como Diagrams-as-code). Un extra que no está en dicho tweet es Mermaid, herramienta sobre la cual daré un ejemplo en otro post.

Significant Revisions

Nov 21, 2022: Original publication on dariomac.com