Desarrollo guiado por README (2010)
(tom.preston-werner.com)- Desarrollo guiado por README: un enfoque en el que se escribe primero el README al desarrollar software
- Se escucha mucho sobre diversas metodologías y técnicas de desarrollo como TDD, BDD, Extreme Programming y SCRUM
- Pero, si el software que desarrollamos no satisface las necesidades del usuario, todo lo demás carece de sentido
- Incluso una implementación perfecta no vale nada si sigue una especificación equivocada, y una biblioteca hermosa sin documentación casi no tiene valor
- Si el software resuelve el problema equivocado o no se sabe cómo usarlo, se genera un problema grave
Solución: escribir primero el README
- Por qué hay que escribir primero el README
- Antes de escribir código, pruebas o historias, hay que empezar por el README
- Escribir el README es un paso esencial para crear buen software
- Hasta que no se escribe sobre el software, no queda claro qué se va a programar
- El README permite pensar el proyecto de forma estructurada
- Beneficios de escribir primero el README:
- Oportunidad de pensar el proyecto de forma estructurada:
- Se puede pensar el proyecto de forma ordenada sin necesidad de cambiar código
- Antes de programar, se puede reflexionar sobre la estructura del proyecto y la API que incluirá
- Contar con una documentación excelente:
- Al inicio del proyecto, se puede redactar la documentación con alta motivación e interés
- Escribir el README después suele ser aburrido y puede hacer que se omitan detalles importantes
- Mayor eficiencia en el trabajo en equipo:
- Otros desarrolladores del equipo pueden recibir información sobre la interfaz antes de que el proyecto esté terminado y empezar otras tareas con confianza
- Trabajar sin una interfaz clara puede requerir una gran reelaboración del código
- Base para discusiones concretas:
- El simple acto de redactar en texto una solución propuesta permite que todos discutan con una idea clara
- Oportunidad de pensar el proyecto de forma estructurada:
- Características del desarrollo guiado por README (RDD):
- RDD puede verse como un subconjunto o una versión limitada de Documentation Driven Development (DDD)
- RDD limita el documento de diseño a un solo archivo para evitar el problema de escribir especificaciones en exceso
- Fomenta mantener bibliotecas pequeñas y modularizadas
Conclusión
- Hay que considerar el proceso de escribir el README como un verdadero "acto creativo"
- En este documento deben expresarse todas tus ideas ingeniosas, y el documento en sí debe ser una prueba de creatividad y capacidad de expresión
- El README debe ser el documento más importante del código base, y escribirlo primero es el enfoque correcto
9 comentarios
Ya sea software, una novela o una película, al crear cualquier tipo de obra,
si uno la diseña y la planifica primero sobre el papel, quizá sea más fácil cuidar los detalles. :)
Había estado olvidando lo más básico todo este tiempo, pero ahora tengo que ponerlo en práctica.
Decidimos llamarlo "diseño básico".
Sin querer, se parece bastante a la forma y al contexto en que trabajo.
Parece que esa parte termina materializándose en forma de "README".
Cuando trabajo, suelo dejar claros el What, Why, How, etc., y mientras avanzo voy dándole forma a lo que hay que hacer, así que se parece bastante.
Desarrollo guiado por README
Como somos una organización de investigación, siempre he tenido muchas dudas sobre cómo publicar los resultados investigados en forma de código, pero siento que el desarrollo guiado por README podría encajarnos muy bien. Parece un enfoque que vale la pena considerar desde la etapa inicial de una investigación.
De forma similar, cuando hago backend, a veces empiezo escribiendo de manera aproximada la documentación de la API mientras veo la pantalla,
y me ha ayudado bastante a reducir la prueba y error.
Visto de cierta forma, da la impresión de resaltar la importancia de definir primero con precisión el problema que hay que resolver.
Es un texto de 2010, pero lo encontré mientras veía otros artículos y pensé en compartirlo.