En nuestro campo [software engineering] se habla mucho de velocidad de entrega. Pasamos mucho tiempo optimizando como utilizamos el tiempo, fechas de entrega y distribución de trabajo. Tenemos metodologías y sistemas para asegurar que esto fluya correctamente. “Move fast and break things” todavía es un mantra para muchos.

Comic de XKCD con alguien tomando una entrevista mencionando su mantra de moverse rapido y romper cosas. Tiene una lista de los trabajos de los cuales lo han despedido

A mucho les encanta gritar “practicamos Agile developmenten” y se adhieren a los rituales diversos rituales para asegurarse que así sea. Sin embargo sprint tras sprint, milestone tras milestone, volvemos a dialogar de los mismo problemas que teníamos con otras metodologías,scope creep, requerimientos no documentados, expectativas que cambian, entre otros. Además, seguimos con la misma falta de documentación.

En los pasados meses, mi equipo se ha dado la tarea de escribir engineering specs para enfocar la conversación en lo que conocemos y lo que no sobre un problema. Me gustaría compartir lo que he aprendido sobre la practica.

Una búsqueda rápida por el internet les darán un sinnúmero de excelente artículos enumerando los beneficios de escribir un engineering spec (ver enlances al final del articulo). Por esto, prefiero entrar en las lecciones que he aprendido en los pasados meses de estar escribiendo estos documentos con mucha frecuencia.

Crea una plantilla (template)

Escribir este tipo de documento puede intimidar. Mucho tiempo se puede ir pensando cómo mejor estructurarlo, que partes incluir y que es importante. La creación de un template es de infinita ayuda para reducir estas incertidumbres  y ayudar a concentrar en el contenido.

Pueden ver el template que estoy utilizando. Una gran parte viene del articulo A practical guide to writing technical specs por Zara Cooper. Les recomiendo que vean el Markdown crudo ya que tiene comentarios dando una breve explicación de cada sección.

Modifiquen el template mientras escriban

La función de la plantilla es ayudarte a escribir. Esta perfectamente bien remover secciones que no hacen falta o añadir secciones que te ayuden a escribir un mejor spec.

Un buen ejemplo son las secciones de prior art y current solution en el template que compartí. Proyectos nuevos pueden no tener estos ejemplos o la necesidad de mencionarlos. Es mejor tener un documento que su estructura demuestre finalidad que tener a un lector preguntarse si esta incompleto.

Traten el template como un documento viviente

Durante los pasados meses mi equipo se ha dado la tarea de validar que nuestro template realmente es útil para nosotros. Iteramos sobre él, lo compartimos con el resto de la organización de ingeniería y pedimos retroalimentación. Esto a creado una aceptación del mismo y otros equipo lo han adoptado para sus necesidades.

Escribe el spec antes de implementar

Esto es más importante de lo que uno se imagina.

Un propósito de un engineering spec es de proponer soluciones a un problema y de retar asunciones que podamos tener de dichas soluciones. Encuentro que el tener un documento escrito que exponga estas asunciones ayuda en la construcción de prototipos que puedan sostener o desaprobar las mismas.

Una vez el spec esta aceptado también sirve de documentación durante las etapas de planificación y desarrollo. Esto ayuda a mantener todo dentro del alcance (scope) del proyecto y a evitar scope creep

Pongan un limite de tiempo para escribir

De todas las lecciones creo que esta fue las más obvia que no vimos hasta después de escribir varios specs.

Es de suma importancia que mantengan el proceso de escribir un spec activo. Estos documentos pueden volverse complicados y extensos. Existe el potencial de dejarlos sin terminar para atender otros asuntos de “mayor importancia”. Esto puede paralizar el proceso y llevar al equipo a brincar directamente a una etapa de implementación.

El mantener un limite de tiempo no solo ayuda a imponer un termino para completar el documento, sino que puede ayudar a identificar si el scope del problema es muy extenso. Esto presenta una excelente oportunidad para revaluar el problema y quizás dividirlo en tamaños más manejable.

Hagan el escribir el spec parte de su proceso de desarrollo

Escribir un spec conlleva tiempo y esfuerzo. Se debería considerar igual de importante que la implementación de código. Incluye esta tarea como cualquier otra en tu sesiones de planificación, ya sea agile, scrum, sprints, no importa. El trabajo se debería representar correctamente y ayuda al equipo ir aprendiendo cuánto realmente toma definir, investigar y escribir un spec.

Mi equipo esta incluyendo estos documentos como parte de los spikes en nuestro sprint. Nos ayuda a mantener el proceso del spec corriendo, nos permite comunicar a las otras partes de la organización donde estamos con entregables y nos da un artefacto de entrega al final del sprint que nos sirve para demos.

Incluye el mantenimiento de tus spec en tus tareas

Un spec realmente no esta terminado del todo. Durante el proceso de desarrollo los requerimientos pueden cambiar, el equipo aprende más sobre el tema o se prueba que la solución no es la correcta. Tu spec debería reflejar esto.

La actualización de un spec deberían formar parte de tu proceso de desarrollo, tal como actualizas la documentación del proyecto. Esto puede ser parte de las tareas del desarrollador al someter cambios al código, de un desarrollador senior o un tech lead, hasta de un product owner.

Para ayudarnos, mi equipo incluye preguntas en nuestro pull request template donde el desarrollador puede indicar si hace falta algún cambio en documentación.

Esto no resuelve el problema del todo, pero sí nos mantiene pensando en estas tareas.

Para terminar

El valor de crear especificaciones técnicas es bien alto tanto para el desarrollador como para su equipo y organización. Escribir estos documentos nos permite pensar sobre soluciones alejados de los detalles de implementación, abre las puertas a colaboración de otros equipos y personas en tu equipo y puede ahorrar tiempo de implementación. Dicho todo esto, esto no es una solución mágica para crear buen software, sino parte del proceso.

Toma el tiempo para evaluar si esta practica funciona para tus proyectos y equipos. Como toda disciplina toma tiempo sentirse cómod@ en su practica. Existen varios artículos que te pueden ayudar a comenzar. Estos son algunos que me ayudaron a mí:

  1. A practical guide to writing technical specs por Zara Cooper
  2. How to write awesome tech specs por Della Anjeh (@blackqueentech)
  3. Writing Technical Specification, and Why it Matters por Anggie Aziz
  4. On Writing Tech Specs por Chuck Groom

Gracias por leer y nos vemos en la próxima.