Para muchos equipos de software, la documentación se escribe después de que se ha establecido la funcionalidad y se han tomado decisiones de diseño. Cuando esto sucede, las preguntas sobre cómo entender o utilizar una función a menudo no surgen hasta mucho más tarde.
Nuestro equipo comenzó a reconocer este patrón en nuestro propio trabajo hace más de un año. Las funciones suelen funcionar como se esperaba, pero son difíciles de usar o explicar. La documentación va por detrás de su publicación. Las decisiones de diseño importantes existen principalmente en conversaciones o código, más que en artefactos compartidos que otros pueden revisar, cuestionar o construir.
El desarrollo basado en documentos es un marco que surgió de estas observaciones. En este artículo, describiré qué nos impulsó a adoptarlo, cómo cambió nuestro trabajo diario de ingeniería y qué hemos observado después de un año de usarlo en la práctica.
Las reflexiones en este artículo provienen de mi experiencia trabajando en Landscape, el producto de gestión de sistemas de larga data de Canonical. Nuestro equipo incluye ingenieros de backend, ingenieros de redes, ingenieros de documentos, diseñadores de gestión de productos y experiencias de usuario. Como muchos equipos responsables de productos maduros, a menudo equilibramos el mantenimiento continuo y la introducción de nuevas funciones mientras trabajamos con otros equipos de ingeniería.
Qué significa en la práctica el desarrollo basado en documentos
El desarrollo basado en archivos es un enfoque de ingeniería de software que trata los archivos como una parte integral del proceso de desarrollo en sí, en lugar de algo que sucede después del hecho.
La documentación aquí no se refiere sólo a la documentación del usuario. Incluye documentos de diseño de ingeniería, documentos para el usuario y cualquier documento interno utilizado para la colaboración dentro del equipo o con otros equipos. En la práctica, este proceso proporciona un orden más claro a seguir para nuestro trabajo funcional.
Así es como se ve el desarrollo basado en documentos para nuestro equipo:
Una nueva característica comienza con un documento de diseño, que describe de manera clara y concisa el diseño propuesto para la característica, incluido el estado existente del sistema, el problema que se está resolviendo, las razones para resolver el problema y el diseño que se pretende implementar. Escribir documentos de diseño nos obliga a tomar decisiones claras desde el principio y abre la puerta a debates más colaborativos sobre el diseño funcional.
Una vez que se acuerde el diseño, comience a redactar la documentación del usuario antes de escribir cualquier código. Esta etapa obliga a los ingenieros a prestar mucha atención a la experiencia del usuario. Si una característica es difícil de explicar con claridad, refleja algunos problemas no resueltos dentro del diseño mismo.
A medida que avanza el desarrollo, el código y la documentación continúan evolucionando juntos. La documentación del usuario debe reflejar el estado actual de la funcionalidad, y el acto de escribirla seguirá informando las decisiones de implementación.
Cuando el artículo está completo, también lo está la documentación, no porque fuera apresurada al final, sino porque ayudó a darle forma a todo el trabajo.
El desarrollo basado en documentos no consiste en mejorar la documentación del usuario de forma aislada. Este es un enfoque que considera la experiencia del usuario como una preocupación central de los productos y las prácticas de ingeniería.
Antes de adoptarlo: lo que no funciona
Antes de adoptar el desarrollo basado en documentos, el desarrollo de funciones seguía un patrón general con el que muchos ingenieros probablemente estén familiarizados: surge un requisito, algunos miembros del equipo discuten un enfoque, tal vez registran notas informales o un documento de diseño parcialmente completado, y luego comienza la implementación.
Este no es un trabajo de diseño funcional. No Sucedió, pero la mayor parte se resolvió en la conversación o se reflejó en el código. Los archivos de usuario (cuando existen) se escriben cerca del final del desarrollo y, a menudo, no están listos cuando se completa la función.
No hacemos un intento consistente de iluminar toda la experiencia del usuario. Las primeras discusiones se centraron en el comportamiento y la viabilidad del software; A menudo, estas decisiones se tomaban a medida que resolvíamos problemas, en lugar de definir de antemano cómo los resolveríamos. Cuando revisar el diseño de funciones es difícil, las preguntas sobre cómo los usuarios finales descubren, comprenden o utilizan una función a menudo surgen mucho más tarde.
Con el tiempo, los efectos negativos del sistema anterior se hicieron cada vez más evidentes: documentación faltante, casos extremos confusos y comentarios o ideas que llegaron después de que la característica ya había tomado una forma fija.
Cambio importante: documentación como parte del proyecto
El primer impacto que observé después de que nuestro equipo adoptó el desarrollo basado en archivos fue que cambió la forma en que los ingenieros interactuaban con sus propias suposiciones sobre las nuevas funciones. Escribir la documentación en las primeras etapas del proceso puede hacer que las brechas en el diseño y la implementación sean más evidentes. Si bien es posible implementar una característica sin resolver completamente los casos extremos o las ambigüedades, es mucho más difícil hacerlo. explicar Una característica sin notar áreas poco claras.
Este cambio es especialmente evidente durante la fase de diseño funcional. Los documentos de diseño se convierten en un punto de referencia estable que informa cada etapa del desarrollo. Formalizar el papel de los documentos de diseño cambia el carácter de nuestros métodos y discusiones de desarrollo. Es menos probable que las conversaciones giren únicamente en torno a los aspectos internos de una función y es más probable que incluyan preguntas sobre cómo los usuarios experimentan la función. Debido a que el documento de diseño claramente hace suposiciones y compensaciones, también proporciona una base más sólida para crear documentación de usuario más adelante.
Ejemplo: evitar errores costosos
En algún momento durante el año, estábamos diseñando una función que estaba estrechamente relacionada con el trabajo realizado por otro equipo y la futura integración con sus sistemas. Nuestro enfoque inicial fue permitir que Landscape se apropiara más de la gestión de las identidades de los usuarios, que es un área relativamente nueva para nosotros como producto.
Escribimos documentos de diseño detallados y creamos maquetas de UX adjuntas, considerando cuidadosamente los detalles de implementación de Landscape, la experiencia del usuario y los planes a largo plazo. Debido a que este trabajo está estrechamente relacionado con el trabajo realizado por el equipo interno de gestión de identidad, compartimos este documento con ellos para su revisión.
La inversión en el equipo de gestión de identidad tiene dos impactos importantes. En primer lugar, aportan conocimientos de dominio sobre la gestión de identidades. Esto nos ayudó a darnos cuenta de que el enfoque que propusimos sería complejo de mantener en el tiempo y pondría a prueba las capacidades de nuestro equipo. En segundo lugar, notaron que nuestro diseño podría complicar la integración futura con sus sistemas porque no era consistente con sus planes de producto. Por ejemplo, nuestro esquema de base de datos propuesto es incompatible con su modelo de datos y el esfuerzo para hacerlos compatibles es demasiado grande en esta etapa.
Basándonos en estos comentarios, finalmente reevaluamos la función en sí y luego decidimos no implementar el diseño como se recomendó. Redujimos significativamente el alcance de esta función y evitamos perder tiempo en trabajos complejos e innecesarios que requerirían reelaboración en el futuro.
Sin un desarrollo basado en documentos, es posible que no hubiéramos explorado el diseño con tanta profundidad ni habríamos producido suficiente documentación para respaldar dicha revisión. Las funciones que decidimos no crear son el resultado directo de tratar la documentación como una parte fundamental de nuestro proceso de ingeniería.
¿Qué ha cambiado con el tiempo?
A medida que el desarrollo basado en archivos se convierte en parte de nuestro flujo de trabajo normal, se producen algunos cambios.
Documentación de usuario como parte del proceso de desarrollo.
La documentación del usuario se convierte en una parte integral del desarrollo de funciones en lugar del producto final. Debido a que se escribe y modifica junto con el código, los ingenieros están más involucrados en la documentación y se centran más en cómo los usuarios entienden la funcionalidad. Con el tiempo, esta participación resultó en mejoras significativas en la calidad. La documentación se vuelve más clara, más completa y más consistente con el comportamiento real del producto.
Esta exposición también tuvo algunos efectos secundarios. Los ingenieros también se familiarizan más con nuestra documentación en su conjunto, no porque se les haya ordenado hacerlo, sino porque contribuyeron a ella y la entendieron. Es más probable que noten lagunas, cuestionen la documentación existente y realicen mejoras voluntariamente.
Artefactos más claros y mejor colaboración
La colaboración entre los diferentes roles de nuestro equipo también ha mejorado, principalmente porque producimos documentos de mayor calidad en una fase más temprana del proceso. Escribir diseños y experiencias de usuario más claros y completos hace que sea más fácil compartir su trabajo para su revisión sin requerir conocimientos previos en profundidad sobre Landscape o su código base. Las discusiones entre ingeniería de backend, ingeniería de redes, documentación, gestión de productos y diseño de UX se basan en una comprensión compartida de la funcionalidad, no en un resumen o recuperación. Es más fácil conciliar el propósito, el uso y la experiencia del usuario de una función.
Cambios en la cultura del equipo.
Uno de los cambios más importantes que he observado es nuestra cultura de equipo. Es más fácil hablar de la documentación, el diseño y la experiencia del usuario porque se convierten en parte de nuestro trabajo diario de ingeniería en lugar de cuestiones periféricas. La perspectiva de todo nuestro equipo cambió: mejorar los componentes del producto orientados al usuario se convirtió en un objetivo compartido prácticano solo compartir valor.
límite
Aunque logramos muchos resultados positivos al adoptar el desarrollo basado en archivos, no resolvió cada pregunta. Este proceso está diseñado para el desarrollo de nuevas funciones, por lo que no aborda directamente los problemas existentes en nuestra documentación ni sus desafíos de mantenimiento continuos.
En primer lugar, la adopción ha sido gradual y desigual. Nuestro equipo adoptó rápidamente la fase de diseño de documentos, pero redactar documentos para el usuario en las primeras etapas del proceso requirió un cambio mayor en la forma en que estábamos acostumbrados a trabajar. Esta parte del ejercicio tardó un tiempo en resultar natural y útil, y no todos los miembros del equipo la adoptaron al mismo tiempo.
También aprendimos que el proceso en sí requiere cierta flexibilidad. No todas las funciones garantizan la misma profundidad de documentación en cada etapa: algunas funciones se benefician más de un trabajo de diseño más profundo, mientras que otras son más complejas en las fases de implementación y documentación del usuario. Repetimos nuestro proceso a medida que avanzamos, ajustando cómo lo aplicamos a diferentes tipos de desafíos en lugar de seguirlo rígidamente.
Pero en el camino sucedió algo más silencioso. Adaptamos nuevos procesos para satisfacer nuestras necesidades, lo que permitió al equipo compartir experiencias resolviendo problemas desconocidos y aprendiendo cómo afrontar la incertidumbre juntos.
Mirando hacia el futuro
El desarrollo basado en archivos no resuelve todos nuestros problemas, pero nos brinda una base sobre la cual construir. Al hacer que nuestra experiencia de usuario y diseño funcional formen parte de nuestro trabajo diario de ingeniería, creamos las condiciones para que crezcan otras prácticas y, como resultado, la calidad de nuestro trabajo ahora es mucho mayor. Antes de que comience la implementación, el diseño será más reflexivo y considerado, y la nueva documentación del usuario estará escrita de manera más clara para la audiencia, más consistente con el comportamiento del producto y lista para cuando se completen nuevas funciones. También hemos podido construir sobre esta base, introduciendo prácticas como el mapeo de historias de usuario en nuestro trabajo de ingeniería y aprovechando el mismo enfoque en los procesos y recorridos de los usuarios que el desarrollo basado en documentos ayudó a establecer.
Durante el año pasado, el desarrollo basado en documentos nos ayudó a establecer un proceso y un lenguaje compartidos para pensar juntos sobre nuestros productos, código, documentación y experiencias de usuario. Las prácticas y los productos de nuestro equipo continúan evolucionando, pero ahora son más claros y están más conectados con la forma en que los usuarios interactúan con los productos que creamos, con menos suposiciones no probadas.
