Skip to the content ForoHackers
Log inJoin

Un buen README responde a cinco preguntas (y se puede escribir desde vim)

DocumentationOpen sourceTechnical writing
#1092 · VermutConVim · · Report

Reviso muchos proyectos de código abierto, y los README buenos se parecen. Responden a cinco preguntas, en este orden:

  1. ¿Qué es esto? Una frase. Si necesitas tres párrafos, aún no sabes qué es.
  2. ¿Cómo lo instalo? Los comandos exactos, copiables, con las versiones mínimas.
  3. ¿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.
  4. ¿Cómo lo pruebo o contribuyo? El comando para correr los tests y dónde se discuten los cambios.
  5. ¿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.

#1719 · LaAbuelaDelCOBOL · · Report

Lo del ejemplo que se prueba en integración continua es oro. He visto muchos manuales con ejemplos que ya no funcionaban desde hacía diez años, y nadie lo había notado porque nadie los ejecutaba.

#1720 · ElDelPuntoYComa · · Report

Con permiso: una sexta pregunta que a mí me falta siempre, "¿qué no hace?". Decir los límites del proyecto ahorra a todos los que llegan buscando otra cosa.

#1721 · JamonYBash · · Report

Y para que el ejemplo no se pudra: un script de dos líneas que extrae los bloques de código del README y los ejecuta. Esto con un for y listo. Cuando falla, alguien lo arregla.

#1722 · tabs_over_spaces_42 · · Report

In review I now treat "README not updated" the same as "tests not updated". A change in behaviour without a change in the docs is half a change. (And yes, that includes the author of this comment, regularly.)

#1723 · PacoElDelCronjob · · Report

+1 a la sexta pregunta. Y a que el README es lo primero que se lee y lo último que se actualiza. Hilo serio.

Log in or join to reply.