Escribiendo una propuesta técnica

Escribir una propuesta técnica es algo en lo que he visto a más de una persona sufrir, a veces luchando por convencer a otros de algo en lo que cree, otras por no saber ni cómo ni dónde proponer nuevas iniciativas. No suele haber mucha documentación sobre como hacerlas, pero es que es muy probable que tampoco tengas una forma establecida de cómo hacerlo en tu empresa, y por si fuera poco no existe una única forma, un estándar de como hacerlo, de hecho varía mucho de empresa en empresa, e incluso dentro de la misma empresa, por ejemplo es habitual en empresas grandes tener dos propuestas, una para el comité técnico (CTO, comité de arquitectura, comité de technical leads, etc) y otra para presentar a la dirección (CEO, CPO, board, etc). 

En esta Newsletter voy a intentar cubrir cómo preparar una propuesta técnica para tener más posibilidades de éxito, teniendo en cuenta cosas como la audiencia, stakeholders o apoyos dentro de la organización (buy-in). Este texto lleva en mi cabeza años porque como mencionaba arriba, he visto muchísimas propuestas y esfuerzos fracasar por errores muy comunes, desde no cubrir algo tan básico como por qué es relevante para el negocio como por presentarla poco trabajada a stakeholders clave, generando desconfianza en la iniciativa. Y algo interesante es que después de pasar por bastantes empresas nunca he visto ninguna organización que te enseñen a hacerlo sino que se aprende “on-the-job”. 

Una propuesta técnica no es simplemente un documento donde haces un “brain dump” (algo así como volcar todo lo que tienes en la cabeza) con tus ideas y soluciones a un problema, es un medio para comunicar a otros porqué un problema es importante, el análisis que has hecho para resolverlo y la solución propones después de sopesar todo.

La newsletter ha quedado demasiado larga y por eso no cubro en detalle el proceso de aprobación, comités y demás. Es decir, a quién y dónde presentarlas. 

¿A qué me refiero cuando hablo de propuestas técnicas?

Me refiero a propuestas de calado, es decir, propuestas técnicas que a menudo requieren de un cambio transversal, que puede afectar a toda la empresa. Por ejemplo, un cambio de arquitectura, de tecnología, de herramientas, etc. Es decir, aquí no me estoy refiriendo a propuestas que se quedan dentro del equipo y que no tienen un impacto más allá del mismo.

En la mayoría de empresas cuando quieres llevar a cabo una iniciativa a nivel técnico de cierta envergadura, requiere de la aprobación de ciertos stakeholders. Estos últimos dependen mucho de la organización, podría ser el CTO, podría ser un comité de arquitectura. 

Porqué, propósito

Uno de los problemas que me he encontrado con muchas propuestas es que se olvidan de mencionar porqué es necesario lo que proponen, cuál es la motivación y sobre todo como está atada al negocio. ¿cómo beneficia a los clientes? ¿cómo repercute esto en la empresa? Lo que propones tiene sentido, pero ¿es necesario?
Si tienes evidencias de la necesidad incorpóralas también, por ejemplo si estás intentando resolver un problema de escalabilidad añade una lista con todos los incidentes provocados, todos los bugs relacionados, etc.

Muchas propuestas solo hablan de tecnología, de lo buena que es, de las bondades que tiene pero se olvidan de mencionar porqué eso beneficia a la empresa y no solo hablo de propuestas con un impacto directo en $$, también propuestas más meramente técnicas, por ejemplo, mejorar la experiencia del desarrollador (como mejorar el CI). Que una propuesta sea correcta o traiga ciertas mejoras no significa directamente que sea buena para la empresa en este momento.

Es posible que estemos mejorando una parte del sistema pero que éste no sea el mayor dolor o necesidad que tenemos ahora mismo. Es decir, el mero hecho de que cambiar de Python a Go mejore la performance del sistema no es suficiente, si no está relacionado con un beneficio para el negocio no merece la pena la inversión. O para que cambiar un componente de Python a Go para ganar un 1.1x si el problema que está limitando el sistema es como escalamos la DB y solucionar eso nos llevaría a un 10X…

Debemos tener en cuenta el “coste de oportunidad". Los recursos de la organización son limitados, y cuando haces algo, estás renunciando a hacer otra cosa. ¿Existe otra cosa que aporte más valor que migrar a Go? ¿Qué dejamos de hacer por hacer esto? Por ejemplo, podemos proponer una iniciativa para reducir deuda técnica demostrando que gracias a eso reduciremos el KTLO y con ello vamos a poder entregar más rápido.

Y esto me lleva a mencionar algo que muchos software engineers pierden de vista, el "momentum", saber cuándo presentar una propuesta es tan importante como la propia iniciativa. Es importante conocer la situación actual de la empresa, del sistema, de tu área si la empresa es muy grande. Así cómo saber aprovechar las situaciones como las crisis para presentar ciertas mejoras. 

Por ejemplo si estamos con el agua al cuello porque el sistema no escala horizontalmente, no es el mejor momento para arrancar una iniciativa para lograr que el CI gane un 20% de velocidad. Y al contrario, si acabamos de sufrir un incidente y hemos tardado una hora para poner el fix en producción debido al CI, es un buen momento para lanzar esa iniciativa. 

Por último, si quieres proponer un cambio debes de convertirte en un experto del sistema actual. Es muy difícil acertar en una solución si no conoces bien el problema.

https://twitter.com/flopezluis/status/964224286159458305

Buy-in y stakeholders

Otro gran error mencionado ya anteriormente, es presentar propuestas poco trabajadas. Es decir, antes de presentar la propuesta a quiénes sean que la tienen que aprobar asegúrate de que está completa, de que cubre todo lo que esperan ver (más sobre esto en la sección documento técnico). 

Evita el lenguaje ambiguo, adjetivos como “falla un poco”, “lo mejora sustancialmente”, “creemos que”, la propuesta tiene que ser precisa e incorporar datos, métricas que den soporte a nuestras afirmaciones. Es muy útil, siempre que sea posible incorporar un prototipo.

Lo mejor que puedes hacer es pedir mucho feedback a otros peers, pedir consejo/mentoring a otros líderes técnicos de la organización. Por ejemplo, si estás en un equipo y tienes una propuesta para cambiar algo transversal a la empresa, asegúrate de que tu equipo ha revisado y dado feedback a tu propuesta. Como regla general, si todo está ok. Pregunta de nuevo, nadie hace una propuesta bien a la primera.

Además si en tu empresa contáis con figuras como arquitectos, principals, o así pide a alguna de ellas que te ayuden con la propuesta. Eso es algo simple pero importante, no solo la propuesta estará más trabajada sino que tendrás un aliado, un sponsor que te apoyará cuando la organización tenga que tomar la decisión. Si no tienes este tipo de figuras en tu empresa, piensa en quién en tu organización tiene el conocimiento técnico para poder darte un feedback válido y crítico. 

Además del feedback técnico es muy importante que también busques un feedback más ligado al negocio, para eso entiende quién son tus stakeholders principales. Igual que antes, esto no solo es importante porque te darán feedback sobre si tu propuesta responde a sus preguntas, lo es también porque ganarás apoyos. Y esto es algo que merece una mención especial, es el famoso buy-in. Cuando vas a presentar una propuesta que es transversal y que puede tener un impacto importante en la organización, tener aliados es clave para que salga adelante. Esas personas son las que te avalarán y darán su apoyo en el momento de la decisión. Por eso es importante que identifiques quienes son e involucres a los que puedas. No interpretes esto como "envíales la propuesta cuánto antes", nada más lejos de la realidad. De lo que hablo es que tienes que ponerte conversaciones con ellos y empezar a machacar cabezas con el problema que quieres resolver y porqué es importante. Recuerda, es mucho más importante que la gente se vaya con la sensación de que hay un problema que resolver que con lo bonita que es tu solución.

Te contaré algo que me pasó hace unos años cuando trabajaba en Google, mi equipo (Spacejam), tenía que hacer propuestas técnicas para modificar el framework de Android pero, nosotros no formábamos parte del framework así que necesitábamos su aprobación para todo. Durante los primeros meses, nos costaba una barbaridad avanzar en cualquier iniciativa, hasta el punto de tener una bloqueada durante todo un mes. Hablando con mi director me propuso una solución muy sencilla, “nos vamos a San Francisco”, así que unas semanas más tarde allí estábamos, con el único objetivo de tomar café con las personas más clave y ¿sabes qué? Funcionó.

Smells

Por último, antes de ir al documento en sí, hay smells que hacen que todo el mundo levante la ceja y que se cuestione y mucho la propuesta. Cosas como cambiar todo un sistema que está en producción funcionando, hacer un refactor gigante, Big bang rewrites.

Las propuestas muy grandes como reescribir algo por completo suelen asustar a la gente por el riesgo que conllevan, es mucho más fácil que se apruebe una propuesta donde el riesgo es mucho más bajo. Así que si puedes plantear una propuesta en fases donde el beneficio empiece a verse en las primeras fases y después se vaya iterando será más fácil que se apruebe. 

Incluso si puedes es una buena idea, dividir la propuesta técnica en varias e ir atacando cada una de forma separada en diferentes momentos.

Lo mismo ocurre con iniciativas que evidencian falta de análisis (ejemplo típico poner el foco en la media de la request en lugar de mirar a los percentiles), de conocimiento del sistema, etc. 

Intenta ser lo más explícito posible con las diferentes alternativas y sus pros y cons, sino hacemos esto lo más probable es que nos encontremos con gente pidiendo ese análisis, debates sobre si se podría resolver de esta u otra forma cuando en realidad ya es algo que has analizado, así que mejor ser explícita.

Es importante que dejemos claro cuáles son los objetivos y cuáles no. Esto ayuda a evitar debates estériles y a centrar la conversación.

Una vez que compartas el documento con la gente, manténlo vivo, es decir, reacciona al feedback que te dan, para descartarlo o para cambiar el documento pero no dejes los comentarios ahí sin más. Eso hace que el documento sea muy complicado de leer y seguir. Si tomas decisiones, refléjalas en el documento, si haces pruebas igual.

Documento técnico

El documento técnico varía mucho en función de la empresa e incluso del departamento. Por ejemplo, cuando trabajaba en Google Android, el documento técnico tenía algunas secciones obligatorias por temas legales como los Logs que se iban a añadir, o como se iba a ver afectado el sistema android debido a esta nueva feature (e.g memoria, disco, etc).
Pero hay muchos formatos distintos como RFDs o los ARDs, aquí puedes ver más ejemplos y las empresas que los siguen.  

Un ejemplo muy bueno y muy bien documentado, como suelen acostumbrar, es Gitlab, No solo tenéis el documento técnico sino cómo lo usan y ejemplos.

https://twitter.com/ArturoHerrero/status/1699426508790546554

Termino compartiendo un documento sencillo y muy común en muchas empresas:

Technical proposal title

Purpose

The purpose describes what the service or feature does. Why is this relevant for the business?
Try to keep this to one sentence.

Background and context

Why do we need this feature? What problem are you trying to solve? What is the context for another team member reading this document? 

Requirements

What are the outcomes this service or feature must exhibit? These could be metrics like response time or characteristics of a component built on the frontend (e.g. responsive to various mobile device sizes). You can include user stories here to describe the requirements.

• Goals

• Non-Goals

Solutions

This is the longest part of the design doc and requires the most research, planning, and preparation. This is your engineering approach to solving the technical problem.

It can include pseudocode, database schemas, flow diagrams, wireframes, components, input validation, security considerations, API endpoints, sample API requests/responses, and countless other things.

You should also mention alternative approaches to solving the problem and the tradeoffs. Example:
Option 1

- Pros

- Cons

Option 2

- Pros

- Cons

Implementation plan / Phases

There might be some overlap between the detailed design and the implementation plan, but this section includes the actionable items (i.e. epics and tasks) required to complete and ship the service/feature.

Tests

What tests will you write? How will you ensure this service/feature works? How will you know when this service/feature stops working? Which tests would guarantee that the system/feature implements the expected behaviour?

Monitoring, Alerts & Runbooks

How do you launch this service/feature? How does someone else troubleshoot it?
Which metrics would display that the system/feature is working as expected? How will you monitor it?