
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 A lo largo de los años, he trabajado en todo tipo de proyectos: grandes, pequeños, caóticos, sobreingenierizados, "temporales", supuestamente bien estructurados y todo lo demás. Y sin embargo, un patrón ha sido cómicamente consistente: La documentación siempre falta, está desactualizada o enterrada en algún rincón olvidado de Confluence, custodiada por una marca de tiempo de 2019. Cada proyecto   tener documentación. afirma Cada equipo   que la mantendrá actualizada. promete Y cada desarrollador dice con confianza: "No te preocupes, lo escribiré más tarde", que, como todos sabemos, es el equivalente en documentación de decir  "el cheque está en el correo". Después de ver este ciclo repetirse más veces de las que me gustaría admitir, me di cuenta de algo simple pero brutalmente cierto: 
 
 La documentación solo sobrevive si vive lo más cerca posible del código, porque los desarrolladores (incluyéndome a mí) somos criaturas perezosas. Y de eso, llegó otra realización: el principal problema con la documentación desactualizada es el hecho de que la mayoría de los equipos no la consideran parte del ciclo de desarrollo principal, dejándola para más tarde o conformándose con un par de especificaciones pre-desarrollo que ya tenían en algún lugar de Confluence. Para escribir documentación significativa, primero discutamos qué tipo de documentación existe para un componente de software: Formas de documentar el código (que los desarrolladores podrían usar) Una vez que aceptas que la documentación tiene que vivir cerca del código, la siguiente pregunta es   estructurarla. cómo En la práctica, he descubierto que la buena documentación no es un único artefacto, es un pequeño ecosistema de capas, cada una sirviendo a un propósito y audiencia diferente. Para ese proyecto que mencioné (escrito en Java + Spring Boot), identificamos cuatro tipos principales de documentos: 1. Especificaciones del cliente Estos son documentos convencionales, generalmente compilados por un experto en el dominio. Idealmente, son ricos en lenguaje ubicuo y proporcionan descripciones agnósticas al código de los casos de negocio, en otras palabras, todo lo que un ingeniero necesita para comprender verdaderamente el problema en cuestión. Desafortunadamente, en la realidad, estos documentos a menudo terminan almacenados en algún lugar de Confluence, compartidos con el equipo al principio de un proyecto, y luego casi nunca se actualizan. No me malinterpreten: estos documentos   importantes. son Extraer conocimiento de los expertos en el dominio debería ser una prioridad para cualquier equipo de ingeniería. Pero las especificaciones evolucionan, los plazos estresan a todos y esos documentos originales se convierten lenta pero seguramente en una base desactualizada. El conocimiento de los requisitos cambiantes, los casos extremos y los giros del proyecto termina viviendo en el código o, ¡peor aún!, en las mentes de los desarrolladores senior. Para abordar esto, dejamos de escribir especificaciones en archivos Word aleatorios o páginas de Confluence destinadas a ser olvidadas y las acercamos lo más posible al frente:  el repositorio de código. Comenzamos a almacenarlos como archivos Markdown (.md) dentro del repo, generalmente en una carpeta docs/. En entornos de microservicios grandes, estos documentos pueden incluso justificar un repositorio dedicado enlazado como submódulo de Git. Los submódulos a menudo se pasan por alto, pero son una forma poderosa de mantener organizados los ecosistemas de varios repositorios. Para una lectura más detallada sobre submódulos, recomiendo encarecidamente esta publicación de blog:  . enlace 2. README - La puerta de entrada para humanos Si las especificaciones del cliente son la enciclopedia, el README es la puerta de entrada. Y aun así, es una de las piezas de documentación más pasadas por alto en los proyectos de software. Irónicamente, casi todas las plataformas de control de versiones (GitHub, GitLab, Bitbucket) renderizan automáticamente el README en la página principal del proyecto. Es lo primero que ve cualquier desarrollador al llegar al repositorio. A pesar de esto, los README a menudo están sorprendentemente vacíos, dolorosamente desactualizados o llenos del temido "TODO: escribir documentación más tarde", que, por supuesto, nunca sucede. Un buen README no es opcional. Es el único documento que es más probable que se lea, porque requiere  . Y como está en la raíz del repo, es más probable que los desarrolladores lo actualicen mientras trabajan en el código. Es documentación que vive en el camino de menor resistencia. cero clics Un README bien escrito debe responder a las preguntas más importantes que un desarrollador tiene en los primeros minutos de encontrarse con un proyecto: 
 
 
 
 
 
 
  una declaración concisa de propósito y contexto, sin palabrería de marketing. ¿Qué hace este servicio/proyecto/componente? -  instrucciones de tiempo de ejecución, variables de entorno, configuración de dependencias y cualquier comando específico del proyecto. ¿Cómo lo ejecuto localmente? -  pruebas unitarias, pruebas de integración, configuración de datos de prueba y cualquier herramienta relacionada con las pruebas. ¿Cómo lo pruebo? -  una breve explicación de la disposición de los directorios, los módulos clave y dónde encontrar las partes importantes del código. ¿Cómo está estructurado el proyecto? -  Scripts de despliegue, notas de CI/CD, permisos requeridos o matices de la plataforma. ¿Cómo lo despliego?  enlaces a documentación generada, notas de arquitectura, referencias de API y documentos de diseño centralizados. ¿Dónde puedo leer más? - El README es la puerta de entrada al proyecto. Establece expectativas, reduce el tiempo de incorporación y brinda a cada ingeniero, nuevo o experimentado, un punto de orientación claro. Cuando se mantiene adecuadamente, se convierte en el documento único más valioso en todo el repositorio. 3. JavaDocs - Documentación que el compilador te molesta para mantener JavaDocs: usualmente invisibles, a menudo olvidados, pero absolutamente esenciales cuando algo se rompe. En la práctica, documentar proyectos Java a menudo cae en dos extremos: o  , o   porque "el código se auto-documenta". La verdad, como siempre, está en el medio. sobrecomentar cada línea trivial ningún comentario en absoluto Para nuestro proyecto, tomamos la decisión consciente de documentar  . Eso significó: solo lo que era genuinamente necesario 
 
 
 
 
 usar   para que los términos de dominio coincidieran exactamente con lo que había en las especificaciones del negocio lenguaje ubicuo explicar el   detrás de las decisiones no obvias, no el   que el código ya revela por qué qué documentar clases de dominio centrales, interfaces y flujos de trabajo complejos evitar muros de comentarios que simplemente repiten el nombre del método de forma verbosa JavaDocs, cuando se usan correctamente, sirven como la microdocumentación que aclara la intención sin abarrotar el código. Y a diferencia de las páginas de Confluence, JavaDocs viene con una ventaja incorporada: 
 
 El compilador realmente se queja cuando se desincronizan. Si renombra un parámetro pero olvida la etiqueta JavaDoc, la compilación se lo recuerda. Si elimina un método pero deja referencias de comentarios obsoletas, el IDE se ilumina como un árbol de Navidad. Esta suave fricción es exactamente por lo que JavaDocs tienden a ser más precisos que otras formas de documentación: son molestos de descuidar. Para mantener todo centralizado y evitar "islas de documentación", también usamos  . Doxygen Doxygen es una herramienta de generación de documentación ampliamente utilizada en el desarrollo de software. Si bien se usa principalmente en la comunidad C++, lo usamos para agregar los JavaDocs en una referencia consistente y navegable, una página HTML. Tiene una serie de características que JavaDoc no ofrece, por ejemplo, los diagramas de clases para las jerarquías y el contexto de cooperación, más páginas de resumen y muchas más. Esto nos dio una vista limpia y unificada de toda la base de código sin depender de pistas dispersas del IDE. 4. Código limpio - La documentación que no necesita mantener Finalmente, la forma de documentación más infravalorada es también la que los desarrolladores respetan menos hasta que realmente la necesitan:  el código limpio. Los comentarios envejecen. Las especificaciones se desvían. Los README se ignoran. Los JavaDocs pueden volverse obsoletos. Pero el código bien escrito (claro, intencional y expresivo)   documentación. es Como dijo famosamente el Tío Bob:  "El código limpio se lee como prosa bien escrita". Y en la práctica, eso significa: 
 
 
 
 
 
 
 clases y métodos con nombres que revelan su propósito funciones que hacen una cosa y la hacen bien terminología de dominio utilizada consistentemente en todo sin astucia por sí misma sin "comportamientos sorpresa" ocultos en efectos secundarios sin abstracciones innecesariamente profundas que requieran un doctorado para entender El código limpio es el único artefacto garantizado para sobrevivir a refactorizaciones, sprints, rotación de personal y caos organizacional. Siempre está sincronizado con el comportamiento del sistema porque...   el comportamiento del sistema. es Una regla simple surgió para nosotros con el tiempo:  Si necesitas un párrafo de comentarios para explicar un método, el verdadero problema es el método. Cuando el código es expresivo, todo lo demás se vuelve más fácil: los JavaDocs se vuelven más ligeros y enfocados, el README se reduce porque la incorporación se vuelve obvia, las especificaciones se vuelven más claras porque el modelo de dominio refleja el vocabulario del negocio. El código limpio no elimina la necesidad de documentación; la  . ancla Garantiza que todas las demás formas de documentación (especificaciones, READMEs, JavaDocs) refuercen la verdad en lugar de compensar una implementación poco clara. Al final, el código limpio es la documentación que no requiere mantenimiento, ni integración de CI, ni herramientas. Es la explicación más honesta y confiable de lo que realmente hace el sistema. Uniendo todo: una canalización de documentación viva Después de refinar cómo escribíamos la documentación, el último paso fue asegurarnos de que no solo se creara, sino que se entregara continuamente y siempre fuera accesible. Para eso, construimos una canalización de documentación que convirtió nuestras especificaciones, archivos README y JavaDocs en un único portal de   unificado. documentación viva Como queríamos que nuestros documentos vivieran lo más cerca posible de nuestro código, decidimos desplegar todo a través de  , lo que nos brindó una solución de alojamiento sin esfuerzo y controlada por versiones, directamente vinculada a la base de código. Github Pages no es exclusivo de Github (GitLab, por ejemplo, también tiene páginas de GitLab); es otra característica útil de los sistemas de control de versiones populares sobre los que recomiendo una lectura adicional:  . GitHub Pages enlace Para compilar todo en un conjunto de páginas coherentes, utilizamos  Sphinx. Sphinx es un potente generador de documentación escrito en Python. Toma archivos fuente escritos en reStructuredText o Markdown y los traduce a varios formatos de salida, incluyendo HTML, PDF y ePub. Sphinx se encargó de la estructura, la navegación y la temática. Doxygen alimentó a Sphinx con JavaDocs autogenerados usando el plugin  , lo que nos brindó una referencia de API totalmente navegable directamente desde el código fuente. Mientras tanto, el README raíz sirvió como el punto de entrada inmediato para los desarrolladores que exploraban el repositorio, enlazando sin problemas al sitio de documentación generado. Breathe Cada fusión en la rama principal activaba un trabajo de CI que reconstruía la documentación, asegurando que el portal reflejara los últimos cambios de código, actualizaciones de API y decisiones de diseño. Nada vivía de forma aislada. Nada requería sincronización manual. Y crucialmente, nada estaba a más de un clic de distancia. Esto convirtió nuestra documentación de un artefacto estático a un ecosistema continuamente actualizado que los desarrolladores realmente usaban, porque estaba integrado directamente en su flujo de trabajo diario y vivía junto al código. Conclusión: la documentación es nuestra responsabilidad, no nuestra carga Al final del día, escribir documentación no es opcional. Es parte de nuestro trabajo como profesionales de la ingeniería. Los futuros compañeros de equipo dependen de ella. La incorporación depende de ella. El mantenimiento, la fiabilidad e incluso la claridad arquitectónica dependen de ella. Pero aceptar esa responsabilidad no significa que la documentación tenga que ser dolorosa. Manteniendo los documentos cerca del código, automatizando lo que se pueda automatizar y confiando en herramientas inteligentes como Markdown, JavaDocs, Doxygen y Sphinx, eliminamos la fricción que normalmente mata los esfuerzos de documentación. Convertimos algo que tradicionalmente se siente como una tarea en una extensión natural del desarrollo diario. Y cuando combinamos eso con código limpio, buenos READMEs y especificaciones ricas en el dominio, todo el ecosistema se vuelve autosostenible. La documentación no necesita ser perfecta, solo necesita ser accesible, precisa y viva. Cuando construimos sistemas que alientan a los desarrolladores a actualizar la documentación tan fácilmente como escriben código, todos se benefician: el equipo, el producto y, lo más importante, el pobre alma que hereda el proyecto seis meses después. La buena documentación no nos hace menos perezosos. Simplemente hace que ser perezoso sea compatible con la creación de un gran software.

The is an opinion piece based on the author’s POV and does not necessarily reflect the views of HackerNoon.

Read My Stories

Este audio es producido en el idioma original de la historia!

Si tu documentación tarda dos clics en abrirse, felicidades: ya está desactualizada.

About Author

COMENTARIOS

ETIQUETAS

ESTE ARTÍCULO FUE PRESENTADO EN

Related Stories

Aumente su productividad con estas 18 herramientas para desarrolladores 🚀🔥

Crecimiento de las criptomonedas: creación de perfiles de usuarios eficaces

Creación de productos criptográficos centrados en el usuario: la importancia de los comentarios de los clientes

Navegando por las aguas: desarrollo de aplicaciones RAG de nivel de producción con lagos de datos

Aumente su productividad con estas 18 herramientas para desarrolladores 🚀🔥

Crecimiento de las criptomonedas: creación de perfiles de usuarios eficaces

Creación de productos criptográficos centrados en el usuario: la importancia de los comentarios de los clientes

Navegando por las aguas: desarrollo de aplicaciones RAG de nivel de producción con lagos de datos

Light-Mode

Classic

Newspaper

Minty

Dark-Mode

Neon Noir

Minty

HN StartUps