Escribir es más difícil que programar

Problemas de pequeños y grandes

He tenido la suerte de trabajar en empresas tecnológicas muy diferentes. Startups chicas, empresas grandes como Facebook Meta y también una startup en crecimiento: Fintoc.

En todas he visto dos grandes problemas:

1. La falta de visibilidad de lo que otros están desarrollando.
2. La deuda técnica que se genera cuando dos distintos equipos generan soluciones completamente distintas para problemas similares. Con esto existe un gran riesgo de repetir código, inducir bugs y complejizar las soluciones de forma innecesaria.

Una de las mejores cosas de trabajar en una startup en crecimiento es que tienes un impacto real en la cultura y dirección de la empresa. Aunque no tenía claro cómo solucionar estos problemas, sí sabía que no quería seguir repitiéndolos en el joven equipo de Fintoc. Conversando con Lukas (co-founder de Fintoc) sobre cómo mejorar esto, me propuso investigar en la comunidad open source. Era obvio: por mucho tiempo la comunidad open source había estado comunicándose de forma asíncrona entre muchas personas.

Hace más de 40 años crearon un tipo de documento conocido como RFC (Request for Comments), publicaciones que documentan los protocolos, procedimientos y estándares del funcionamiento del internet.

Los RFC eran la clave para solucionar este problema.

RFC o como los llamamos nosotros: Engineering Review Documents

Los RFC han sido extremadamente importantes en el desarrollo de software y en el mundo open source: la implementación del protocolo IP se hizo en uno. Otro RFC de culto es la transmisión de datagramas IP usando palomas. 😂

Grandes empresas como Uber, Stripe o Google, ya habían usado esto como inspiración para organizarse. Todas usan documentos parecidos pero con distinto “branding”: Design Documents, Engineering Review Documents o Architecture Design Records. Nosotros bautizamos nuestros RFCs como Engineering Review Documents (ERDs). ⚡️

La idea era que nos sirviera para planificar y también para ponerse al día muy rápido de por qué las cosas están como están en el código. Pero también sabíamos que esto era solo una parte del problema. Una cosa es tener la herramienta y otra muy distinta es usarla.

¿Por qué escribir?

En los dos años que llevamos escribiendo hemos aprendido mucho de por qué hacerlo es tan importante para un dev.

La idea principal de escribir es poner un punto intermedio entre las ideas y el código. El código por definición es concreto y definido, en cambio las ideas son todo lo contrario. Escribiendo te das cuenta que hay una serie de decisiones que no se habían tomado en la discusión de la idea. Escribir y explicarte bien es más difícil de lo que parece y te hace reflexionar sobre si está bien o no lo que estás haciendo. Te permite darte cuenta si realmente entiendes lo que estas haciendo.

Este proceso nos ahorra mucho tiempo. Obliga al equipo a coordinarse y también a que todos estén de acuerdo con el diseño y la implementación de un nuevo feature. El proceso parte con los involucrados en un proyecto poniéndose de acuerdo con alguna implementación. Luego un representante escribe el documento.

💡Suena fácil. Ya están todos de acuerdo. ¿Sólo hay que escribir lo que se conversó o no?

Pero llega el momento de revisar el documento y salen las preguntas: “pero qué pasa con este caso borde? ”, “no me refería a esto cuando lo conversamos” o “qué pasa si cambiamos esto, no rompe este otro proyecto?”

Es muy importante tener estas preguntas y resolverlas. Respondiéndolas es cuando se disminuye el riesgo del proyecto a casi cero.

Mucho mejor tener estas preguntas y descubrir que no estábamos pensando lo mismo ahora, que en la mitad de un proyecto, ¿o no?

En resumen, los ERDs:

• Nos permiten identificar problemas de diseño antes de implementarlo en código.
• Ayudan a que el equipo completo entienda los cambios que se están haciendo.
• Distribuyen el conocimiento del equipo: todos pueden aprender de las decisiones que otros devs en el equipo toman y pueden aprender sobre cómo enfrentarse a distintos problemas técnicos.
• Sirven como documentación para proyectos futuros. En más de una ocasión me he encontrado leyendo documentos más viejos para ver por qué algunas cosas están así en el código.
• Fuerzan a que en todos los proyectos se tomen en cuenta áreas que a veces pueden olvidarse, como seguridad, estabilidad o cualquier otro aspecto técnico que nos importe en el equipo.
• Te obligan a tomar decisiones. Incluso decisiones de negocio. A veces muchas cosas pasan por alto hasta que llega la implementación o a un ERD en donde se necesita el input de otras áreas de la empresa y necesitamos ponernos de acuerdo con una decisión.

¿Cómo trabajamos?

Como cualquier startup, partimos con una versión muy simple. Cuando el proyecto era complejo, el dev encargado tenía que escribir un documento explicando cómo iba a implementarlo, y por qué lo haría así. No tenía un formato ni nada. El siguiente requisito fue tener que explicar qué trade offs se hicieron. Después explicar los riesgos. Y así fuimos avanzando.

Mientras el equipo crecía (ahora somos 15 devs 😳) resultó muy útil tener estos documentos. Explican las decisiones que hemos tomado, y por qué algunas cosas son como son. Terminamos motivando a que todos en el equipo hicieran sus propios ERDs y también que todos participaran de la revisión de estos.

Hoy es parte fundamental del proceso de desarrollo del equipo. Casi ningún proyecto se hace sin este primer paso. Y gracias a esto, hoy tenemos documentadas gran parte de las decisiones que hemos tomado.

¿Cómo logramos coordinar al equipo? Basándonos en lo que otras startups más grandes como Uber o Stripe estaban haciendo y luego iteramos hasta llegar a un proceso que se ajustara a nosotros.

Terminamos llegando a las siguientes reglas:

1. Todo proyecto que no se considere un cambio trivial necesita un ERD: el objetivo acá es planificar antes de desarrollar cualquier cambio.
2. Utilizar un template de documento: sirve para seguir un estándar que busca establecer los riesgos del proyecto y cómo se desarrollará junto al equipo.
3. Definir quienes serán los reviewers del ERD: qué devs estarán a cargo de la revisión del documento técnico. Estos son los que sí o sí deben aceptar los cambios propuestos.
4. Enviar el ERD a todo el equipo: esto permite que cualquier dev de Fintoc pueda revisar qué cosas se están desarrollando y por qué, además de tener la oportunidad de comentar el documento para levantar dudas o aprender de otros devs en el equipo. Los ERDs son públicos para todo el equipo, dev o no.

Ahora el riesgo de iniciar cualquier proyecto es casi cero. Todas las dudas se resuelven antes de que se programe una sola línea de código.

¿Cómo se ven nuestros Engineering Review Documents?

Un ERD es un documento técnico que busca explicar las decisiones y trade offs que se están tomando para realizar un proyecto. Por lo mismo si un ERD se parece más a un manual de lo que se implementará sin hablar sobre los trade offs y riesgos que existen, probablemente no era necesario.

Para lograr esto creamos un template que se debe completar cada vez que se quiera proponer algún cambio grande. Todos nuestros ERDs tienen la misma estructura:

<sub>- **Reviewers**
- **Definición**
   - Contexto
   - ¿Por qué haremos esto?
   - Scope
   - Solución propuesta
- **Consideraciones técnicas**
   - Cambios de arquitectura
   - Cambios a la API pública
   - Cambios a la API privada
   - Dependencias
   - Testing
   - Consideraciones de seguridad
   - Deploy
   - Migraciones
   - Métricas y monitoreo
   - UI & UX
   - Consideraciones de soporte
   - Como afecta los SLAs
- **Soluciones descartadas**</sub>

‍

Este template ha cambiado mucho con el tiempo. A medida que hemos ido creciendo hemos tenido que ir considerando más aspectos como SLAs, migraciones de datos, monitoreo y mucho más. Es muy probable que para cuando leas esto ya existan más aspectos que estemos considerando. 👀

Si un proyecto no involucra todas las áreas que consideramos importantes, es necesario agregarlo (por ejemplo: Cómo afecta los SLAs = no afecta). Esto permite a los devs del equipo que revisan el documento ver las secciones que según el autor no importan (removiendo el sesgo o bias), y considerarlas de todas formas para ver si algún caso borde se nos escapa.

Todos pueden ser reviewers

La pregunta del millón: ¿los documentos los tienen que revisar todos? ¿no quita mucho tiempo?

Y la respuesta es que no todos tienen que revisarlo, pero sí pueden. Y sí, se lo enviamos a toda el área de ingeniería. Hasta hoy no ha sido problema, no es como que escribimos miles de documentos todas las semanas.

En Fintoc nos gusta mucho la transparencia, al nivel en que toda la comunicación se hace por canales públicos. Ningún mensaje se envía por privado, aunque esto da para otro post. Creemos que si el equipo tiene toda la información a su disposición podrá tomar las mejores decisiones desde su punto de vista.

El resultado de esto es que cuando un dev comparte su solución a un problema que me gusta, me dan ganas de meterme a leer el documento y aportar. Esto es genial. Los ERDs se vuelven lugares de discusión para aprender mucho de todos en el equipo, incluso si no soy yo quien va a programar.

Qué hemos aprendido

Ya llevamos casi tres años trabajando así. El proceso no partió como se ve y de seguro no será igual mañana, pero hemos aprendido mucho.

El nivel del equipo ha mejorado porque fuerza un estándar de calidad mínimo en cualquier desarrollo que queramos hacer. Hemos logrado evitar silos de información incluso cuando devs del equipo deben trabajar solos.

Nos ha permitido formar una cultura dev que busca el aprendizaje y mejorar con cada decisión que tomamos. También nos permite a todos como devs aprender y compartir conocimiento con el resto del equipo.

Y lo mejor de todo: hemos visto cómo este proceso escala con Fintoc.

‍

Si te gustaron los ERD, bienvenido/a a implementarlos en tus proyectos personales o en tu trabajo. Puedes escribirme si tienes dudas, ¡feliz de compartir experiencias!