A lo largo de los años, he trabajado en todo tipo de proyectos – grandes, pequeños, caóticos, sobre-ingenieros, “temporales”, supuestamente bien estructurados, y todo lo que está entre ellos. The documentation is always missing, outdated, or buried in some forgotten corner of Confluence guarded by a 2019 timestamp. Cada proyecto Para tener documentación. reivindicaciones Cada equipo Lo mantendrán actualizado. promesas Y cada desarrollador dice con confianza: “No te preocupes, lo escribiré más adelante”, que, como todos sabemos, es la documentación equivalente a decir: “El cheque está en el correo”. Después de ver este ciclo repetirse más veces de lo que me gustaría admitir, me di cuenta de algo simple pero brutalmente verdadero: 
 
 La documentación solo sobrevive si vive lo más cerca posible del código, porque los desarrolladores (incluido yo) son criaturas perezosas. Documentation only survives if it lives as close to the code as possible—because developers (myself included) are lazy creatures. Y de eso, otra comprensión vino - el principal problema con la documentación obsoleta es el hecho de que la mayoría de los equipos no la consideran como parte del ciclo principal de desarrollo, dejándola para más tarde o haciendo debido con un par de especificaciones pre-dev que ya tenían en algún lugar en Confluence. Para escribir una documentación significativa, primero discutiremos qué tipo de documentación existe para un componente de software: Ways to Document Code (That Developers Might Actually Use) Ways to Document Code (que los desarrolladores podrían usar de hecho) Una vez que acepte que la documentación debe vivir cerca del código, la siguiente pregunta es para estructurarlo. 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 de las cuales sirve a un propósito y público diferentes. Para ese proyecto que mencioné (escrito en Java + Spring Boot), identificamos cuatro tipos principales de documentos: 1. Client Specs Idealmente, son ricos en lenguaje omnipresente y proporcionan descripciones código-agnosticas de casos de negocio - en otras palabras, todo lo que un ingeniero necesita para entender realmente el problema a la mano. Desafortunadamente, en realidad, estos documentos a menudo terminan almacenados en Confluence, compartidos con el equipo al comienzo de un proyecto, y luego casi nunca se actualizan de nuevo. No me equivoques: estos documentos Es importante. son Pero las especificaciones evolucionan, los plazos estresan a todos, y esos documentos originales lentamente pero seguramente se convierten en una base obsoleta. El conocimiento de los cambios de requisitos, los casos de borde y los pívots del proyecto terminan viviendo en el código - o peor! - en las cabezas de los desarrolladores superiores. Para hacer frente a esto, dejamos de escribir especificaciones en archivos de Word aleatorios o en páginas de Confluencia destinadas a ser olvidadas y las movemos lo más cerca posible de la primera línea: the code repository. Comenzamos a almacenarlos como archivos Markdown (.md) dentro del repo, generalmente en un docs / carpeta. En entornos de microservicios grandes, estos documentos pueden incluso justificar un repositorio dedicado vinculado como un submodulo de Git. Los submodulos a menudo se olvidan, pero son una forma poderosa de mantener organizados los ecosistemas multi-repo. Para más lecturas sobre los submodulos, recomiendo este post de blog - . Enlace 2. README – The Front Door for Humans Si las especificaciones del cliente son la enciclopedia, el README es la puerta de entrada.Y sin embargo, es una de las piezas de documentación más olvidadas en los proyectos de software. Irónicamente, casi todas las plataformas de control de versiones - GitHub, GitLab, Bitbucket - automaticamente muestran el README directamente en la página principal del proyecto. Es la primera cosa que cualquier desarrollador ve cuando aterriza en el repositorio. Un buen README no es opcional.Es el documento único más probable que se lea realmente porque requiere Y porque se encuentra en la raíz del repo, los desarrolladores son más propensos a actualizarlo mientras trabajan en el código. zero clicks Un README bien escrito debe responder a las preguntas más importantes que un desarrollador tiene dentro de los primeros minutos de encontrar un proyecto: 
 
 
 
 
 
 
 ¿Qué hace este servicio/proyecto/componente? - una declaración concisa de propósito y contexto - ningún flujo de marketing. ¿Cómo puedo ejecutarlo localmente? - instrucciones de tiempo de ejecución, variables de entorno, configuración de dependencia y cualquier comando específico del proyecto. ¿Cómo lo teste? - pruebas de unidades, pruebas de integración, configuración de datos de pruebas y cualquier herramienta relacionada con las pruebas. ¿Cómo está estructurado el proyecto? - una breve explicación del diseño del directorio, módulos clave y dónde encontrar las partes importantes del código. Cómo implantarlo: Escritos de implementación, notas de CI/CD, permisos requeridos o matices de plataforma. ¿Dónde puedo leer más? - Enlaces a documentos generados, notas de arquitectura, referencias de API y documentos de diseño centralizados. El README es la puerta de entrada al proyecto.Establece expectativas, reduce el tiempo de inicio y da a cada ingeniero, nuevo o experimentado, un punto de orientación claro.Cuando se mantiene correctamente, se convierte en el documento único más valioso en todo el repositorio. 3. JavaDocs – Docs That The Compiler Annoys You Into Maintaining JavaDocs - generalmente invisible, a menudo olvidado, pero absolutamente esencial cuando algo se rompe. En la práctica, documentar proyectos Java a menudo cae en dos extremos: , o Porque “el código es autodocumentado”.La verdad, como siempre, está en algún lugar en el medio. over-commenting every trivial line no comments at all Para nuestro proyecto, tomamos una decisión consciente de documentar Eso significaba: only what was genuinely necessary 
 
 
 
 
 usar un lenguaje omnipresente para que los términos de dominio coincidan exactamente con lo que estaba en las especificaciones de negocio explicando el por qué detrás de las decisiones no obvias, no lo que el código ya revela Documentación de clases de dominios, interfaces y flujos de trabajo complejos Evitar las paredes de comentarios que simplemente repiten el nombre del método en forma verbosa JavaDocs, cuando se utiliza correctamente, sirve como la documentación de micro-nivel que aclara la intención sin confundir el código. Y a diferencia de las páginas de Confluence, JavaDocs viene con una ventaja integrada: 
 
 El compilador se queja cuando salen de la sincronización. Si renombras un parámetro pero olvidas la etiqueta JavaDoc, la construcción te recuerda. Si elimina un método pero deja referencias de comentario estancadas, el IDE se ilumina como un árbol de Navidad. Esta fricción suave es precisamente la razón por la cual los JavaDocs tienden a permanecer 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 generadora de documentación ampliamente utilizada en el desarrollo de software. Si bien se utiliza 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 clase para las jerarquías y el contexto de cooperación, más páginas de resumen, y muchos más. Esto nos dio una vista limpia y unificada de toda la base de código sin depender de pistas IDE dispersas. 4. Clean Code – The Documentation You Don’t Need to Maintain Por último, la forma de documentación más subestimada es también la que los desarrolladores menos respetan hasta que realmente la necesitan: clean code. Comentarios edad. Specs drift. READMEs se ignoran. JavaDocs puede convertirse en estallido. Pero el código bien escrito -claro, intencional y expresivo- La documentación. es Como dijo el tío Bob, “El código limpio se lee como prosa bien escrita”. En la práctica, esto significa: 
 
 
 
 
 
 
 clases y métodos con nombres que revelan su propósito Funciones que hacen una cosa y la hacen bien La terminología de dominio se utiliza de manera consistente a lo largo del No hay inteligencia para su propio bien No hay “comportamientos sorprendentes” ocultos dentro de los efectos secundarios No hay abstracciones innecesariamente profundas que requieran un doctorado para comprender El código limpio es el único artefacto garantizado para sobrevivir a los refactores, los sprints, el tráfico de personal y el caos organizacional. El comportamiento del sistema. is Una regla simple surgió para nosotros con el tiempo: If you need a paragraph of comments to explain a method, the real problem is the method. Cuando el código es expresivo, todo lo demás se vuelve más fácil → JavaDocs se vuelve más ligero y más enfocado → 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 empresarial. El código limpio no elimina la necesidad de documentación; es Y eso. ANCORES Asegura que todas las demás formas de documentación -specs, READMEs, JavaDocs- están reforzando la verdad en lugar de compensar la implementación ambigua. En última instancia, el código limpio es la documentación que no requiere mantenimiento, integración de CI ni herramientas.Es la explicación más honesta y fiable de lo que el sistema realmente hace. Bringing It All Together — A Living Documentation Pipeline Bringing It All Together - Una Pipeline de Documentación Viva Después de refinar la forma en que escribimos la documentación, el último paso fue asegurarnos de que no sólo se creara, sino que se entregara de forma continua y siempre accesible.Para ello, construimos un tubo de documentación que convirtió nuestras especificaciones, archivos README y JavaDocs en un único, unificado. . living documentation portal Dado que queríamos que nuestros documentos vivieran lo más cerca posible de nuestro código, decidimos desplegar todo a través de Github Pages no es particular a Github (GitLab, por ejemplo, también tiene páginas de GitLab) - es otra característica limpia de los sistemas de control de versiones populares que recomiendo para la lectura adicional - . GitHub Pages Enlace Para compilar todo en un conjunto de páginas cohesivas, usamos Sphinx. Sphinx es un potente generador de documentación escrito en Python. toma los archivos fuente escritos en reStructuredText o Markdown y los traduce a varios formatos de salida, incluyendo HTML, PDF y ePub. Sphinx gestionó la estructura, la navegación y el tema. Doxygen alimentó a Sphinx con JavaDocs generados automáticamente utilizando el Mientras tanto, el root README sirvió como el punto de entrada inmediato para los desarrolladores explorando el repositorio, enlazando sin problemas al sitio de documentación generado. respiración Cada fusión en el principal desencadenó un trabajo de CI que reconstruyó los documentos, asegurando que el portal reflejaba los últimos cambios de código, actualizaciones de API y decisiones de diseño. Nada vivió en aislamiento. Nada requería sincronización manual. Esto convirtió nuestra documentación de un artefacto estático en un ecosistema continuamente actualizado que los desarrolladores realmente usaban, porque se integró directamente en su flujo de trabajo diario y vivía justo al lado del código. Conclusion — Documentation Is Our Responsibility, Not Our Burden 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 ingeniería. Los futuros compañeros de equipo dependen de ella. El embarque 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. Al mantener los documentos cerca del código, automatizar todo lo que puede ser automatizado y confiar en herramientas inteligentes como Markdown, JavaDocs, Doxygen y Sphinx, eliminamos la fricción que normalmente mata los esfuerzos de documentación. Cuando construimos sistemas que alenten a los desarrolladores a actualizar documentos 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 construcció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.

Every

Front

Read My Stories

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

Si su documentación toma dos clics para abrir, se congrega - ya está desactualizada

About Author

COMENTARIOS

ETIQUETAS

ESTE ARTÍCULO FUE PRESENTADO EN

Related Stories

Las capas invisibles: por qué las entrevistas con los usuarios son un activo irremplazable

La guía completa para una migración exitosa a la nube: estrategias y mejores prácticas

¿Quieres ganar un concurso de redacción de HackerNoon? Esto es lo que recomiendan los ganadores del concurso #crypto-api

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

Las capas invisibles: por qué las entrevistas con los usuarios son un activo irremplazable

La guía completa para una migración exitosa a la nube: estrategias y mejores prácticas

¿Quieres ganar un concurso de redacción de HackerNoon? Esto es lo que recomiendan los ganadores del concurso #crypto-api

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

Light-Mode

Classic

Newspaper

Minty

Dark-Mode

Neon Noir

Minty

HN StartUps