A los desarrolladores les encanta compartir código en forma de paquetes, apps, o pequeños módulos. Compartir mola, pero una de las características que muchos desarrolladores olvidan son los archivos README. Este archivo es una de las piezas más importantes de los proyectos y muchos desarrolladores no invierten el tiempo suficiente.
Un README empezó como una guía para desarrolladores. Se podía acceder después de descargar el código y mostraba instrucciones relacionadas con la configuración, instalación, derechos de autor, solución a problemas conocidos y mucho más. Los repositorios de código populares empezaron a poner los readme como página principal del proyecto y se convirtieron de ser información técnica a ser directamente la presentación del proyecto. Este cambio significa pasar de ser documentos para desarrolladores a convertirse en herramientas de marketing con la información básica del proyecto.
Piensa sobre los últimos proyectos open source que hayas visto. Seguramente tenías un problema y necesitabas una solución. Encontraste algo razonable y miraste el readme para ver si realmente sería la solución. Por supuesto, que esta es la razón principal, pero también se deben considerar las siguiente preguntas:
- ¿Resolverá esto mi problema?
- ¿Puedo confiar en este código?
- ¿Puedo confiar en el equipo/desarrollador que lo creó?
- Podría a obtener ayuda si estoy atascado?
- ¿Hay más issues o más pull requests?
- ¿Estoy dispuesto a mantener esto actualizada si este proyecto muere?
- ¿Puedo construir esto de manera más sencilla yo mismo?
Si no te sientes cómodo respondiendo sí a la mayoría de estas preguntas, entonces es hora de seguir adelante. Incluso si un paquete funciona, el desarrollador tiene la responsabilidad de infundir confianza en el proyecto porque nos guste o no tu eres el que estas incluyendo un riesgo en el proyecto.
Trabajando a través de estas preguntas vamos a ver como construir un readme que inspire confianza, responda a las objeciones y muestre a los lectores porqué tu código es digno de incluirse en su proyecto.
Estructura de un readme
La estructura de un readme puede tomar diversas formas. He visto algunos que cubren todos los posibles escenarios y he visto otros con una sola frase «lee el código». Por supuesto, decirle a la gente que lea el código no es lo ideal y el que abarca todos los casos es difícil de conseguir y mantener, pero podemos llegar a un termino medio.
Richard Kim creó el siguiente mapa de calor que muestra como los usuarios ven su readme y esboza una estructura agradable:
Él sugiere una imagen, párrafo inicial, instalación, ejemplos de código y luego continuar con todo lo demás.
Yo propondría cambiar esta estructura y añadir un párrafo de introducción entre la imagen y los ejemplos de código. Aquí está el nuevo esquema:
- Imagen
- Párrafo inicial
- Ejemplos de código
- Instalación
- Configuración
- Todo lo demás… Vamos a desgranar esta estructura y a describir lo que debe lograrse y cual es el objetivo principal.
Imágenes
Las imágenes son importantes y permite a las personas compartir tu proyecto tan solo incluyendo una imagen. También ayudan a crear confianza , mostrando un nivel de atención.
«Una imagen de cabecera o el logotipo con el readme demuestra cuidado en la presentación,» dijo Matt Stauffer, propietario de Tighten.co. «Lo que me hace pensar que es más probable que el código tendrá atención a los detalles y al mantenimiento»
Si te preocupas por la presentación, a continuación, te preocupas aún más por el código. Otro bien detalle es añadir un gif o un video destacando algunas de las mejores características y aspectos más importantes.
Un bucle GIG animado será observado una y otra vez, analizado y entendido. Un párrafo de texto será ignorado. – Taskwarrior Project
A continuación unas cuantas herramientas y recursos para crearlos fácilmente
Herramientas para GIF animados – Licecap es una herramienta gratuita que puede capturar un area de tu escritorio y guardarla. – Droplr – Giphy Capture
Tutoriales para crear Gif animados – Animated Gif Workflow – Designing Gifs
Herramientas de imágenes – Pablo y Sprout Social ambos permiten subir una imagen y poner texto en ella. Perfecta para construir imágenes para compartirlas en redes sociales. – Canva es una aplicación completa que ofrece «assets» tanto gratuitos como de pago
Una vez que tengamos listo todos los recursos, es hora de crear la introducción.
La introducción o «Lead»
La introducción o lead en periodismo, es tu primera oportunidad de interesas al lector y captar al lector para seguir leyendo. Debe ser un par de frases que expliquen exactamente el propósito del código, porqué alguien va a querer usarlo, y como funciona. Responder el qué, por qué y el cómo.
Cuando te sientes a escribir la introducción es importante recordar que tu eres el experto. Tu conoces todo el código. Otros no. Así que tienes que se claro y conciso.
Aquí tienes algunos consejos que vinieron directamente de la página de tendencias de Github:
Ahora vamos a pasar a la creación de ejemplos de código
Ejemplos de código
Después de la introducción es un buen lugar para poner algunos ejemplos de código. En esta sección se da al lector una idea de como queda y que es lo que hace, es la primera introducción a su API.
Por ejemplo, si has escrito una librería para procesamiento de imágenes un ejemplo podría ser cambiar el tamaña y procesarla:
$image = (new Image)->resize(100, 100)->convert(‘greyscale’);O si has escrito un paquete para genera el numero de veces que se ha compartido una URL:
$shares = (new SocialButler)->count($url);Estos ejemplos se utilizan para reforzar la confianza que comenzó e la introducción y conseguir que el usuario empiece a pensar en la cantidad de tiempo que va a ahorrar. Estos ejemplos no son los mismos que en la documentación… eso ya lo veremos más adelante.
Configuración y uso
A continuación viene la parte más grande del readme. La configuración y el uso esbozan todas las cosas que se pueden hacer. Si seguimos utilizando paquetes ficticios, esto sería una lista de todos los métodos de la API y la forma de utilizarlos.
Es un ben momento para pensar en modo «principiante». ¿Van a entenderlo? ¿Serán capaces de resolver su problema con el código? O como [@lizthedeveloper]() dijo:
https://twitter.com/lizthedeveloper/status/677239025799790593?ref_src=twsrc%5Etfw
Your docs don’t have enough:
Simple examples Real-world examples Typical use cases Explanations for beginners
They can never have enough.
Google también realizó un estudio sobre «Cómo los desarrolladores buscan código» que encontró que la búsqueda más común, lo que representa más de un tercio de las encuestas (33.5%), se refería a la API específicamente, información acerca de la librería, o ejemplos funcionales.
No estamos documentando lo suficiente el código que ponemos, esperando a que los usuarios, ya sepan mágicamente cómo usarlo.
Copy Editing
Después de haber pasado todo este tiempo construyendo la documentación, seguro que estas entusiasmado por sacarla. Sin embargo, es el momento de dar un paso atrás y empezar a editar para asegurarse de que todo está claro, comprensible y libre de errores. La edición de un Readme no es diferente de la de una entrada del blog o de cualquier otro contenido. Me gusta «dejar descansar» unos días la documentación para volver a ella con más frescura. Algunas cosas a tener en cuenta son:
- ¿Está todo comunicado con claridad?
- ¿Se podrían mejorar algunas frases?
- ¿Qué pasa son las faltas de ortografía? Una vez hecho este paso y satisfechas estas preguntas se pueden utilizar algunas herramientas para mejorar aún más. Me gustan Grammarly y Hemingway.
Descubrimiento
Después de haber revisado el readme y tenerlo todo listo, ¿cómo vas a hacer marketing con tu código? Cómo dijo una vez DHH «Cualquier cosa que merezca la pena ser liberado, es digno de marketing».
Hay muchas maneras diferentes de hacer marketing con tu código: anunciarlo en redes sociales, escribir un blog, enviárselo a tus amigos por correo electrónico, escribir en un foro, etc. Todos esto merece la pena, pero si no tienes un gran número de seguidores, quizás te sientas como si todo esto estuviese cayendo en saco roto.
Otra opción es publicarlo en sitios de noticias. Hay muchos sitios específicos para cada lenguaje y siempre están buscando contenido. Sin embargo, debido a las limitaciones de tiempo, a los periodistas/bloggers estar al día y probar todo el código que ven. Puedes ayudarles a que su trabajo sea más fácil haciendo una nota de prensa. Ya tienes todos los recursos necesarios en el readme videos, imágenes, gif y puedes crear una historia alrededor del código.
Si deseas más ideas sobre como crear un comunicado de prensa echa un vistazo a este artículo sobre el tema y la forma en la que se lanzó un teclado de iOs a los medios
Readme Generator
Para hacer más fácil la creación de los readme que hemos descrito aquí Michael Dyrynda y Eric L. Barnes han creado un generador de readme. Si quieres echarle un vistazo al código y como lo hicieron mira aquí:
Solo tienes que escribir y puedes ver la vista previa en vivo, a continuación, una vez estés satisfecho solo tienes que pulsar «fetch markdown» para copiar en tus proyectos.
Este artículo es una traducción libre de: https://dotdev.co/how-to-write-a-readme-that-rocks-bc29f279611a
Jesús L.C. - Apuntes de un aprendiz 
Muchas gracias por esto. Estoy aprendiendo español e intento leer en español cuando busco información en Internet. Pero muchos de los textos españoles son demasiado difíciles para mí. Afortunadamente puedo leer su texto sin usar el traductor en cada frase. Y es un recordatorio para mí. Intentaré escribir mi readme para que aquellos que están aprendiendo inglés pueden leerlo.
Me gustaMe gusta