Reviso muchos proyectos de código abierto, y los README buenos se parecen. Responden a cinco preguntas, en este orden:
- ¿Qué es esto? Una frase. Si necesitas tres párrafos, aún no sabes qué es.
- ¿Cómo lo instalo? Los comandos exactos, copiables, con las versiones mínimas.
- ¿Cómo lo uso? Un ejemplo mínimo que funcione de verdad, y que se pruebe en integración continua para que no se pudra.
- ¿Cómo lo pruebo o contribuyo? El comando para correr los tests y dónde se discuten los cambios.
- ¿Con qué licencia? Una línea, y el fichero de licencia en la raíz.
Ejemplo de la parte tres:
## Uso
$ mitool convertir entrada.csv -o salida.json
Lee `entrada.csv` y escribe un JSON con una lista de objetos, uno por fila.
Un truco que me gusta: el README se escribe antes que el código (o al menos a la vez). Si es difícil explicar cómo se usa, el diseño tiene un problema. Y en vim, con el corrector de ortografía (:set spell spelllang=es) y un formateo a 80 columnas, se escribe cómodo. Sí, soy de los de vim hasta la muerte, pero con humor.