- esbuild y Redis son ejemplos de codebases con documentación sobresaliente.
- A través del README, el changelog, los documentos de arquitectura y los comentarios en el código, incluso los usuarios nuevos pueden entender la estructura del codebase, cómo funciona y por qué fue diseñado así.
- Son buenos casos de estudio para desarrolladores que quieren mejorar la documentación del código y de la arquitectura de software.
Por qué es importante una buena documentación
- Al desarrollar software, una buena documentación es esencial, especialmente cuando otras personas van a revisar o contribuir al codebase, o cuando uno mismo necesita consultarlo de nuevo más adelante.
- Los usuarios de software suelen enfrentar dificultades por la falta de documentación.
- Si vas a contribuir a un codebase, mientras mejor sea la calidad de la documentación, más rápido podrás aportar.
- La calidad de la documentación afecta directa o indirectamente la experiencia del autor, de los contribuidores o de los usuarios.
- Los beneficios de una buena documentación son diversos: ahorro de tiempo, aumento de contribuciones externas en proyectos de código abierto, registro de decisiones pasadas, mayor accesibilidad para más usuarios, estructuración del pensamiento y detección de problemas.
La documentación de esbuild
- esbuild es un bundler de JavaScript creado por Evan Wallace.
- El README de esbuild está enfocado en los usuarios finales de la herramienta.
- Mediante enlaces a las secciones principales del documento y una sección llamada "¿Por qué?", explica brevemente por qué elegir esbuild en lugar de otros bundlers.
- Los documentos de arquitectura de esbuild están en el directorio
docs, en los archivos architecture.md y development.md.
- La documentación de arquitectura explica los principios de diseño e incluye no solo texto, sino también gráficos que ayudan a explicar los conceptos.
- El changelog de esbuild es detallado e incluye resúmenes, explicaciones ampliadas y ejemplos de código antes y después de los cambios.
La documentación de Redis
- Redis es una base de datos en memoria.
- El README de Redis comparte varias buenas características con el README de esbuild, pero además está enfocado tanto en contribuidores como en usuarios finales.
- La sección sobre el interior de Redis incluye la disposición del código fuente y explicaciones de los archivos principales.
- Los comentarios dentro del código fuente de Redis ofrecen explicaciones de varios párrafos incluso para una sola línea de código.
Cierre
- Muchos proyectos de código abierto cuentan con una documentación excelente.
- esbuild y Redis resultan especialmente impresionantes por la calidad de su documentación.
- La documentación puede generar una limitación de tiempo a corto plazo, pero a largo plazo ahorra tiempo.
- En proyectos que muchas personas usan o a los que muchas contribuyen, vale la pena replantearse no documentar.
Opinión de GN⁺
- Los casos de documentación de esbuild y Redis destacan para los desarrolladores la importancia de documentar de forma que facilite la comprensión y el mantenimiento del codebase.
- La documentación es un elemento clave para aumentar la sostenibilidad del proyecto y fomentar la participación de la comunidad.
- En el caso de esbuild, además de su función como bundler rápido de JavaScript, parece que su excelente documentación también ha contribuido al crecimiento del proyecto.
- Redis ha tenido un impacto positivo en la comunidad de desarrolladores gracias a una documentación que ayuda a entender con facilidad un sistema complejo de base de datos en memoria.
- Estos casos pueden ayudar a difundir la importancia de la documentación a otros proyectos de código abierto y son especialmente útiles para que ingenieros de software principiantes comprendan cómo documentar sus propios proyectos.
2 comentarios
esbuild tiene un archivo README.md muy bueno, pero el archivo architecture.md presentado en el artículo es realmente hermoso.
Opinión de Hacker News
Antirez, el creador de Redis, escribió en su blog un artículo que explica en detalle sus ideas sobre los comentarios en el código. Identifica 9 tipos de comentarios usados en Redis.
Un artículo bien escrito que incluye ejemplos concretos y capturas de pantalla sobre cómo la documentación de un proyecto puede ser excelente para usuarios, desarrolladores y contribuidores.
Demuestra la atención de los mantenedores a la calidad del repositorio.
Hace recordar la serie "The Architecture of Open Source Applications". Tiene observaciones interesantes.
GitLab tiene reputación de tener una documentación muy buena, aunque no he necesitado usarla mucho personalmente. Queda la duda de si su documentación de arquitectura también es buena.
El proyecto Postgres también presta atención detallada a la documentación, los archivos readme y los comentarios en el código.
Quedé profundamente impresionado por la documentación de arquitectura del proyecto esbuild. Ojalá algunas bases de código en las que trabajé antes hubieran tenido documentos así.
Me encantan los changelogs de los proyectos de código abierto. Son mucho más profesionales e informativos que los de otras entidades con fines de lucro. Crítica a que el changelog de la app del banco ING debería centrarse en informar en vez de intentar ser gracioso.
"La mayor carencia en la comunidad del software libre hoy en día no es el software, sino la falta de buena documentación libre que pueda incluirse junto con el software libre."
Se menciona que Redis ya no es open source. Redis es software "source-available" bajo Redis Source Available License v2 (RSALv2) y Server Side Public License v1 (SSPLv1).