• All
  • All
  • Home
  • About Me
  • What is KanbanCV

Problemas sobre documentaci贸n

2022-11-21

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.

Example of PlantUML

Significant Revisions

Nov 21, 2022: Original publication on dariomac.com

Orange D inside a circle
Dar铆o Macchi
  • Montevideo - Uruguay
  • What is this?
  • Contact me
  • Protected by Copyscape Duplicate Content Detector
  • KanbanCV 漏 2011-2025 Sitemap
  • View Dar铆o Macchi's LinkedIn profile
  • View my twitter
  • View my ResearchGate profile
  • View humans.txt file