Agreguemos ARCHITECTURE.md

 (matklad.github.io)
26 puntos por xguru 2021-02-08 | 1 comentarios | Compartir por WhatsApp

  • Un artículo que propone agregar al repo un archivo que explique la arquitectura del proyecto para facilitar la participación en open source

  • La mayor diferencia entre quienes contribuyen ocasionalmente a un proyecto y los desarrolladores principales es el nivel de comprensión de la arquitectura del proyecto

  • Si no estás familiarizado con la estructura, escribir un parche puede tomar más del doble de tiempo, pero identificar dónde hay que corregir algo puede tomar más de 10 veces más tiempo

  • Escribir un archivo como ARCHITECTURE.md que explique la arquitectura de alto nivel

→ Escribirlo de forma breve para que cualquiera pueda leerlo, y resumir solo las partes que no cambian mucho

→ No intentar mantenerlo sincronizado con el código; mejor revisarlo unas dos veces al año

Cómo escribir el contenido

  • Empezar con una vista panorámica (bird's eye view) del problema que se quiere resolver

  • Un mapa del código un poco más detallado: "¿Dónde está lo que hace X?"

  • Explicar los módulos generales y la relación entre ellos: enlazar lo que hace cada módulo a otros documentos

  • Anotar los nombres de archivos, módulos y tipos importantes

→ Para que quien lea pueda buscarlos por nombre, y no enlazarlos directamente (porque los enlaces pueden romperse)

  • Indicar claramente los límites entre capas y sistemas
  • Buenos ejemplos

Lecturas relacionadas

1 comentarios

 
xguru 2021-02-08

Y también me parece buena la sugerencia de que, si es posible, en el README.md principal se incluya una explicación de cada carpeta del proyecto.

Ejemplo: https://github.com/diem/diem/…

Si es posible, estaría bien agregar una descripción a cada carpeta, y sería bueno que GitHub mostrara ese contenido desde el nivel superior cuando haya un README en la carpeta.

Relacionado con esto, también revisen los Architecture Decision Records.