Documentar tu proyecto: qué herramienta elegir
Documentar es una de las tareas más necesarias y más odiadas a las que se enfrentan los desarroloadores, ingenieros, científicos y todos los trabajadres en algún momento. Muchas veces pensamos que es una pérdida de tiempo o que no sirve para nada, pero todo lo contrario. La documentación es para empezar, la primera imagen que tiene el resto del mundo de nuestro trabajo, y si esa imagen no es buena perderemos muchas oportunidades. Además esa documentación es la base del conocimiento que alguien debe tener para apoyarse en, usar o continuar tu trabajo. Por tanto, viendo su importancia vamos a ver distintas manera o herramientas para hacerlo.
El primer tipo de herramientas que quería traer aquí son las protaformas de gestión de proyectos y código. Muchas de ellas ya cuentan con herramientas propias como Wikis para documentar el trabajo. Aquí entrarían confluence, GitLab, GitHub, etc. Estas herramientas son treméndamente potentes y se pueden integrar con repositiorios de una manera sencilla, lo que aparte de darnos una visualización bastante cuidada, nos permite tener trazabilidad con nuestro trabajo.
Otro tipo de herramientas son las que están pensadas directamente solo para documentar. ENtre ellas quería recoger GitBook. Se trata de una herramienta treméndamente potente para doumentar todo tipo de trabajos, desde código hasta procesos. No es gratis, pero muchas veces el precio de estas herramientas merece mucho la pena.
Aunque en otro nivel, también podemos menciona herramientas de documentación de código como Doxygen. Doxygen es muy conocida para documentación de código, sobre todo en C, C++ y para APIs o SDKs. Se trata de una herramienta mucho más compleja y ardua ya que está en el propio código. Pero a la vez esto tiene sus ventajas, ya que puedes documentar el detalle de lo que has hecho.
Por último quería comentar algunas herramientas, que en principio no están pensadas para documentar, pero que son tremendamente potentes para ello. La primera de ellas es Jekyll. Se trata de la herramienta con la que está hecha este blog. Jekyll convierte texto en una web estática. Pues bien, usando esta idea, podemos contruir nuestra web de docuemntación usando archivos markdown. Además cuenta con temas adaptados a documentar como Just the docs. Y por último pero no menos importante, también recomiendo Notion, el servicio web que vale casi para todo.
Como veis las herramientas son interminables. Estas son algunas de las que existen y he conocido, pero cualquiera de ellas nos va a poner mucho más fácil eso de documentar bien y bonito.