Table of Contents
La documentación técnica es muy importante en el desarrollo de software. Es como una carta de navegación para tu equipo. Documentar tu proceso, sirve como referencia explicando las razones del desarrollo, como opera y cómo utilizarlo. Los equipos de software se refieren a este proceso de documentación técnica cuando hablan de requerimientos, notas en la release o diferentes aspectos en el desarrollo del producto. Utilizan documentos para detallar el código, APIs, y realizar un seguimiento en el proceso de desarrollo de software. Externamente, la documentación se plasma en manuales, guías de usuario para administradores de sistemas, ayuda a los equipos y demás usos.
La documentación técnica sirve para ayudar a los nuevos miembros del equipo a adaptar más rápido a los hábitos de trabajos de la compañía. Comparte información del funcionamiento del producto y el porqué de cada requerimiento. Hace que la curva de aprendizaje de los desarrolladores sea más suave. Y lo hace señalando aquellos puntos de la aplicación en los que ha de centrarse el desarrollador para saber más del contexto de aquella aplicación en la que están trabajando.
La información en la base de datos ha de documentarse sin ninguna duda. Es importante conocer con qué tipo de base de datos estamos trabajando, servidores, diagrama de información, etc. Muestra todas las modificaciones en la estructura así como los tipos y las adiciones de índices. Sirve para tener un mejor muestrario de soluciones ante posibles soluciones que puedan aparecer. En este documento incluye una secciones de preguntas frequentes para lidiar con problemas más recurrentes.
Documentos de instalación y configuración son muy útiles para cuando los desarrolladores necesitan configurar aplicaciones de entorno. Mucho mejor si los pasos a seguir están bien detallados y son fáciles de seguir. De ese modo las soluciones a posibles problemas pueden añadirse con facilidad.
Detalles como el software a necesitar, librerías y versiones de aplicaciones de servidores se pueden incluir para asegurar que el entorno será compatible a lo esperado. La documentación del código es el esqueleto de cada aplicación. Puede dividirse en distintas partes: bloques de comentarios y archivos de documentos más específicos. Información respecto al repositorio del código, instrucciones paso a paso para crear el package de una aplicación o una construcción lista para ser deployada, etc. Una documentación técnica es de gran ayuda para la memoria del proyecto. Es obvio que una lista de tareas ayuda a la organización del equipo, así como diversos estudios sugieren que el hecho de escribir a mano, incrementa la posibilidad de completarla.
Déjame repetir que para un programador, la documentación técnica es un must. La tarea no se basa en hacerlo o no, sino en cómo y qué herramientas sirven para hacer el proceso más eficiente. El hecho de documentar el proceso sirve para conocer todos los aspectos de una aplicación, cosa que beneficia al equipo y mejora la calidad del producto de software. Con la documentación técnica, tienes toda la información necesaria para el desarrollo y el mantenimiento correcto de la aplicación. Así como una mejor transferencia de conocimiento entre developers.
Incluso el mejor software, puede ser inútil si los desarrolladores son incapaces de entenderlo.
Una buena documentación técnica con las mejores herramientas hace que la información sea más accesible, ofreciendo un gran número de “entry points”, ayuda a los nuevos desarrolladores a aprender más rápido, simplifica el producto y ayuda en la documentación de costes. Además genera confianza.
Normalmente, los desarrolladores trabajan con Jira, por ello la herramienta de documentación más popular es Confluence, ya que se complementan el uno al otro. El Confluence de Atlassian es un sistema de documentación técnica que facilita la colaboración y el compartir conocimiento a través de los distintos departamentos y funcionalidades. Puedes utilizar Confluence para recoger las ideas del equipo, conocimiento y distintos planes de acción a seguir. Después ir a Jira y crear esa documentación y tareas relacionadas con esta información.
Razones para utilizar Confluence para una documentación técnica
Todo en un mismo lugar
No tendrás que buscar entre emails, archivos en el ordenador o en el Google drive. Puedes mantener y organizar notas, requerimientos y revisión de códigos directamente en Confluence. No tendrás que ir cambiando entre Jira y demás recursos. Una vez hayas integrado ambas herramientas (Jira con Confluence), tendrás acceso a buena información dentro de Jira.
Informes más simples
Jira genera continuamente información sobre proyectos o problemas que aparecen, pero en muchos casos los equipos no disponen de tiempo o de las habilidades para entender todos los informes con todo detalle. Eso es la razón por la que tiene sentido Jira y Confluence. Puedes presentar informes de estado en cuadros más simples o interfaces de usuario más entendibles para tu equipo.
Edición colaborativa
Confluence tiene templates que puedes personalizar con un muy buen editor de texto para crear y compartir documentos. Esto favorece a una edición más colaborativa.
Mantener a la Stakeholders informados
Confluence permite presentar información de una manera más fácil para todo el equipo, incluidos los equipos que no están en el desarrollo. Los desarrolladores pueden tener todo en JIRA, pero los stakeholders tienden a no ir a buscar problemas técnicos, sino esperar a su solución. Aquí es donde llega Confluence para crear resúmenes, sinopsis, informes, tableros, actualizaciones de progreso o métricas de código.
Conocimiento base
Tu equipo podrá crear y organizar artículos de conocimiento base gracias a un plan que contiene plantillas para artículos prácticos y de resolución de problemas. Las plantillas son totalmente personalizables y ayudarán al equipo a configurar los conocimientos base más rápidamente. En Apiumhub usamos mucho Confluence para crear nuestra base de conocimientos dentro de la empresa (TDD, CI, DDD, Docker, etc.).
Información de proyectos
Esto puede incluir requisitos del proyecto, cronogramas y presupuestos del proyecto, materiales y esquemas, archivos y contratos de los clientes, o cualquier otro detalle administrativo que un miembro del equipo del proyecto deba conocer mientras trabajan en el proyecto.
Confluence es una gran herramienta y en Apiumhub lo hemos estado usando mucho, sin embargo, hay otras herramientas que también usamos para la documentación técnica. No me malinterpretéis, no estoy diciendo que Confluence no sea útil, solo quiero mostrar otras herramientas con otras características que pueden ser una mejor alternativa para tus necesidades. Algunos de ellos son estas:
Herramientas de documentación técnica
Huddle es un centro de colaboración todo-en-uno para tu equipo. Básicamente, tienes todas las herramientas que tu empresa necesita para estar sincronizadas, incluidos el almacenamiento de archivos, la gestión de proyectos y las herramientas de colaboración. Lo que es importante saber aquí es que esta herramienta es para compañías grandes que necesitan un lugar seguro para colaborar como empresa. El precio es de $ 20 por mes por usuario.
Es una plataforma gratuita para el alojamiento de documentación de software con código fuente disponible gratuitamente. Facilita la redacción de documentación técnica al automatizar la creación, el control de versiones y el alojamiento para tí.
Javadoc
Javadoc es un generador de documentación creado por Sun Microsystems para el lenguaje Java para generar documentación de API en formato HTML desde el código fuente de Java.
Markdown
Markdown es un lenguaje de marcado suave con sintaxis de formato de texto plano. Está diseñado para que puedas conertir a HTML y muchos otros formatos utilizando una herramienta con el mismo nombre. Markdown se usa a menudo para formatear archivos “readme”, para escribir mensajes en foros de discusión online y para crear texto usando un editor de texto simple.
Swagger
Swagger ayuda en el desarrollo de todo el ciclo de vida de la API, desde el diseño y la documentación, hasta la prueba y la implementación.
La documentación técnica es esencial en cada etapa del trabajo, el proceso de desarrollo no tienes que esperar a ninguna ocasión específica. La documentación técnica es simplemente un hábito y una disciplina y, contrariamente a lo que mucha gente piensa, no requiere de gran esfuerzo. La documentación técnica va en paralelo con el proceso de desarrollo y no es necesario esperar a que termine todo el trabajo.
Y no te olvides de suscribirte a nuestro boletín mensual para recibir más sobre documentación técnica.
Si te gustó este artículo sobre documentación técnica, te puede gustar:
Ejemplo de desarrollo aplicando TDD – parte 1
Arquitectura de microservicios vs arquitectura monolítica
Scala generics I: clases genéricas y type bounds
Scala generics II: covarianza y contravarianza
Principio de responsabilidad única
Sobre Dioses y procrastinación
Arquitectura de microservicios
Simular respuestas del servidor con Nodejs
Mapa de los “main players”: ecosistema startup y tech en Barcelona
Ecosistema de salud digital en Barcelona
