¿Qué sabe sobre el desarrollo basado en documentos?

¿Por qué necesitamos documentos en el proceso de desarrollo?

¿Qué pasa con esta afirmación de que el código se documenta a sí mismo ?

Consideremos el escenario más común: el código del sistema (ya sea un programa, proyecto o producto) se escribe durante un largo período, y el equipo cambia gradualmente durante este proceso, llevándose consigo ciertos conocimientos sobre el sistema a medida que los desarrolladores se van.

¿Qué podemos hacer en tal caso?

La respuesta más sencilla es escribir una especificación que capture todos los detalles de implementación para garantizar que el sistema cumpla con los requisitos originales.

Sin embargo, un documento de este tipo es muy difícil de redactar con antelación y, durante el proceso de desarrollo, algunos detalles de implementación pueden cambiar (adaptación al mercado/nuevas solicitudes de mecánica, etc.). Entonces, ¿qué podemos idear para mejorar el factor autobús ?

Intentemos seguir un flujo que podría ser una de las posibles soluciones para abordar el problema mencionado anteriormente.

Requisitos y RFC

Primero, necesitamos describir el diseño inicial basado en los requisitos de las partes interesadas y documentarlo. Después de eso, este documento se puede compartir con otros equipos y solicitar sus comentarios: solicitar implementar ciertas características, comentar sobre el diseño inicial, arreglar una determinada interfaz, etc. Un documento de este tipo se puede llamar RFC .

RFC , o "Solicitud de comentarios", es un documento que se distribuye entre las partes interesadas (incluidos desarrolladores, arquitectos y otros equipos) para recopilar comentarios y sugerencias. Es menos detallado que una especificación e incluye sólo el problema inicial, la tarea y el dominio de la solución. Al ser más flexible, permite aceptar activamente cambios en el diseño, asegurando una comprensión profunda de la tarea y facilitando la calidad y la toma de decisiones reflexivas.

Compromiso de diseño y ADR

Bien, hemos definido los requisitos técnicos y recopilado los requisitos de otros equipos . ¿Que sigue?

En esta etapa, es necesario finalizar el diseño del sistema y todas las funciones principales que realizará. Para ello redactamos un ADR .

ADR , o "Registro de decisiones de arquitectura", es un documento que registra decisiones arquitectónicas importantes tomadas durante el proceso de desarrollo de software. Cada ADR describe una decisión arquitectónica específica de alto nivel, su contexto, las alternativas consideradas, la decisión tomada y la motivación para elegir estos detalles específicos sobre otros.

Un documento de este tipo permite que cada miembro del equipo (y también otros equipos) comprenda los principios y valores que sustentan el diseño. Si un nuevo desarrollador se une al equipo años después y pregunta: "¿Por qué lo hiciste de esta manera?", se le puede mostrar este documento, que responderá a todas sus preguntas.

Especificación

Ahora es el momento de escribir el código y sus especificaciones. En esta etapa, trabajamos minuciosamente en cada característica, recopilando simultáneamente toda la información y los detalles de implementación en un documento especial. Este documento debe reflejar los requisitos actuales de bajo nivel para el sistema.

Un punto importante : durante el ciclo de vida del software, dicha especificación puede cambiar significativamente, y eso está bien. Sin embargo, es muy importante permanecer dentro del diseño y la arquitectura originales para evitar que el código base se convierta en algo inmanejable.

Plan de prueba

¿Por qué es necesario? Es fundamental que un plan de pruebas se construya no sobre la base del código escrito de acuerdo con la especificación (escribimos el código y las pruebas para este código para que pasen), sino sobre la base de un diseño que incluya escenarios críticos que debe ser procesado correctamente . También es muy conveniente que pueda enviar dicho plan de prueba para que otros equipos lo revisen (para integraciones o simplemente para pruebas adicionales), dejando claro cómo se comportará el sistema en diferentes situaciones.

¿Qué incluye?

• Todos los escenarios posibles de funcionamiento del sistema.

  • feliz camino
  • camino triste
  • Manejo de errores

• Todas las posibles invariantes que deben mantenerse durante la operación del sistema.

• Pruebas de aceptación para verificar el estado del sistema al inicio (deben considerar el entorno, por ejemplo, datos en la red)

  
  

Finalizamos el diseño , escribimos el código y las especificaciones y compilamos el plan de pruebas . ¡Ya suena bastante sólido! ¿Pero qué más podríamos agregar?

Plan de empleo

Un plan de este tipo podría ser necesario hasta cierto punto para mejorar el factor bus y crear condiciones en las que cualquier miembro del equipo pueda implementar el sistema y verificar su estado.

¿Por qué no podemos prescindir de él? Podemos, pero en el mundo real, equipos grandes donde muchas personas son responsables de diferentes partes del sistema y el proceso de implementación podría delegarse completamente a DevOps. ¿Qué hay de malo en eso? Dado que escribimos pruebas, las pusimos en CI y verificamos las vulnerabilidades, ¿necesitamos algo más? Quizás no, pero a menudo las pruebas no consideran el estado actual del sistema y no prueban exactamente lo que nos gustaría.

Qué plan de implementación podría contener :

• Una descripción completa de las acciones que deben realizarse para que se lleve a cabo la implementación.
• Parámetros de implementación:
  • Variables de entorno
  • Estado inicial
  • Parámetros para el lanzamiento.
• Un plan por si algo sale mal en algún paso
• Un plan de respaldo, si es posible
• El estado necesario al que se debe llevar el sistema en caso de que no sea posible continuar con el despliegue
• Acciones que deben realizarse después de la implementación
  • Notificar a otros equipos
  • Habilite las integraciones necesarias, si es necesario

Nada complicado, ¿verdad? Tener un documento de este tipo para una actualización específica puede mejorar significativamente el factor bus y evitar la dependencia de personas específicas. ¿No es eso lo que queremos?

Conclusión

En el proceso de desarrollo de software, es importante no sólo escribir código, sino también crear documentación que garantice la comprensión y la coherencia en todas las etapas del desarrollo. La documentación puede ser el código en sí , pero la experiencia ha demostrado que la documentación es muy importante para mantener la calidad, estabilidad y escalabilidad futura del sistema, especialmente cuando el equipo cambia durante el desarrollo, y también cuando el proyecto evoluciona y se adapta a nuevos requisitos.

La documentación incluye RFC (Solicitud de comentarios), ADR (Registros de arquitectura), Especificaciones , Planes de prueba , Planes de implementación y más. Esto garantizará la retención del conocimiento en el equipo , simplificará el proceso de integración de nuevos empleados al proyecto y aumentará la confiabilidad general y la resistencia del sistema a los cambios .