La Naturaleza del Software

Comparta esto post

Documentar las decisiones

newsletter.lnds.net

Discover more from La Naturaleza del Software

Un newsletter sobre tecnología y personas
Continue reading
Sign in

Documentar las decisiones

“Just because architecture is supposed to be stable, it does not mean that it should never change.” — Gereon Hermkes

Eduardo Díaz
2 may 2023
4
Comparta esto post

Documentar las decisiones

newsletter.lnds.net
1
Compartir

Bee estaba cansada, pero contenta. La jornada con Al fue genial. Habían pasado cuatro intensivas horas discutiendo la arquitectura para soportar el nuevo feature. La pizarra mostraba un montón de rectángulos y flechas entre sí, ambos la miraron y se rieron.

— Nadie va a entender esto — dijo Bee
— Tienes razón. Veamos. Grábame con tu celular, voy a resumirlo todo.

Entonces Al explicó en poco más de un minuto los dibujos de la pizarra.

Sacaron fotografías y las subieron, junto con el video, al espacio de documentación que tenían. Una Wiki propia del equipo, con cientos de documentos, que contenían procedimientos, manuales, guías y por supuesto diagramas de arquitectura de software.

— Escribiré un ADR

1
y lo subiré al repo del servicio, ¿te parece Al?

El colega de Bee asintió.

— Nos merecemos una cerveza

Bajaron un piso y se dirigieron a una de las terrazas que había en la oficina. Un refrigerador tenía distintas bebidas, incluyendo cervezas. Sacaron dos y brindaron por un trabajo bien hecho. Ahora era tiempo de escribir el código.

Meses después ese video y el ADR les ahorraría más de una discusión. Incluso cuando decidieron hacer un cambio que cambiaba varias cosas de lo plasmado en el video y el documento, lo hicieron con tranquilidad. Marcaron el viejo ADR como obsoleto (deprecated) y escribieron uno nuevo. Con las razones del cambio claras, pero siempre cumpliendo ciertos principios que habían definido cuando el producto fue concebido.

Estos principios de arquitectura son los que guían sus decisiones, y estos principios rara vez cambian, más bien tienden a expandirse. Bee agradecía que esos principios se mantuvieran inalterables. Al a veces los odiaba, pero entendía su necesidad. Finalmente, cuando estaban en dificultad, en posiciones enfrentadas, acudían a los principios, y estos les guiaban para desempatar, o adoptar una tercera posición.

¿Pero de donde salieron esos principios?

Bueno esa es otra historia.

La Naturaleza del Software es una publicación apoyada por sus lectores. Para recibir nuevos posts y apoyar mi trabajo, considera ser un subscriptor pagado o gratuito.

1

Architecture Decision Record, un documento que registra las decisiones arquitecturales de un proyecto. Durante el ciclo de vida de un producto se pueden tomar decisiones que afectan la implementación. Con el tiempo la decisión puede ser cuestionada por diversos motivos, es por eso que un buen ADR da una explicación del contexto y las justificaciones que se tomaron en ese tiempo para tomar la decisión.

4
Comparta esto post

Documentar las decisiones

newsletter.lnds.net
1
Compartir
1 Comentario
Comparta esto discussion

Documentar las decisiones

newsletter.lnds.net
Leo Soto
Escribe La venganza de los nerds
may 3

+1000. De hecho creo que el principio es obviamente generalizable, sean decisiones técnicas o de otros ámbitos https://lavenganzadelosnerds.substack.com/p/tomar-mejores-decisiones

Expand full comment
Responder
Compartir
Superior
Nuevo
Comunidad

No Post

¿Listo para más?

© 2023 Eduardo Díaz
Privacidad ∙ Términos ∙ Aviso de colección
Comience a EscribirObtenga la App
Substack es el hogar para la gran escritura