Llevo abriendo repos open source mas de una década y casi nunca leo el README de arriba abajo. Voy directo a:
- El bloque de código del Quick Start
- Una imagen, si la hay
- La sección de configuración
Si tu README empieza con tres párrafos de misión y visión, tu README es un blog post disfrazado. Pon el npm install en la línea 4. Yo te lo agradezco y tus usuarios también.
Si quieres ponerle sabor, escribe algo ácido como “este README es para los que creen que escribir documentación es opcional” y luego olvídate de él.
Otra cosa es cuando el readme, esta bastante desactualizado, que mierda mas horrible y si esto es una queja, es casi tan horrible como cuando entras a un nuevo trabajo, donde hay mucho codigo, muchos repositorios, muchas personas y nada de documentación y cuando preguntas algo sobre uno especificamente y te dicen el que sabia se fue a otro lado tienes que desarmarlo, en ese momento piensas claro los test unitarios o e2e y no existen ._.
Y mientras hablamos de READMEs inútiles: los badges. Dios mío, los badges. Abres un repo, lo primero que ves son doce escuditos en fila — build passing, coverage 83%, npm version, license MIT, last commit, downloads/week, dependabot, snyk, codecov, hacktoberfest, discord, buy me a coffee — y después de procesar todo eso sigues sin saber qué hace el proyecto. El build passing no me dice nada si no sé qué estás construyendo. Ponlos al final si los quieres poner, o mejor aún, no los pongas.