Te va a interesar!

6/recent/ticker-posts

La importancia de un buen README.md en un repositorio.



Finalmente el verano muestra los dientes en forma de radiación ultravioleta nivel 1000 en Nueva Zelanda. En un rincón con sombra del patio, me traje la laptop y un café para sufrir más el calor y escribirles el primer post del año! Y esta vez voy a arrancar con un post de crecimiento profesional, mitad información útil para programar y mitad información útil para tener mejor visibilidad a la hora de postularnos a trabajos. Qué tal?

Alguna vez les pasó que encuentran una posible solución a un problema en forma de librería y, cuando van a consultar el repositorio para aprender de qué va la cosa... el README no dice nada útil? A mi si, muchas veces.

También ha pasado que al entrar a trabajar en un proyecto, te dan el repositorio usado para automatizar y... otra vez nada en el README. Pareciera una tendencia bastante común en el ámbito del desarrollo y, me atrevería a decir, sobre todo en Automation.

Pareciera que un desarrollador puede pasar 1 hora ajustando nombres de variables, indentation y otras yerbas pero no 10 minutos haciendo un README.md prolijo e informativo.

Primero que nada: Qué es un README.md?


Un README es, como podrán adivinar, un archivo que hay que leer antes de empezar a toquetear código. Se acuerdan antes (y en la actualidad también), que los programas, videojuegos y software en general venía con un archivo de texto llamado ReadMe o ReadMe First?

Apuesto a que era lo primero que leían antes de siquiera ejecutar el juego o programa. Este ReadMe del que hablo hoy es lo mismo! Es la puerta de entrada a un repositorio. Está en la raíz del repositorio y, ese .md que ven como extensión se refiere a MarkDown, un lenguaje útil, flexible y práctico que nos va a permitir añadir links, listas, links a archivos en el repositorio, imágenes y más.

Acá les dejo un link útil de Github con lo que pueden hacer y cómo.

https://guides.github.com/pdfs/markdown-cheatsheet-online.pdf



Por qué es importante hacer un buen README.md?


Creo que a esta altura ya se lo estarán imaginando, pero hay un par de detalles que seguro no pensaron. Empecemos por lo obvio: Va a ahorrarte tiempo de tener que responder cosas básicas que podrías haber informado en un ReadMe.

Imaginá que hiciste un framework increíble que, contra todo pronóstico, lidió perfectamente con las complicaciones de la infraestructura corporativa de la empresa y realiza su labor como un reloj suizo. Un repositorio grande, con muchas partes en movimiento.

Un buen día deciden que entre un nuevo tester a ayudar y tenés que enseñarle a usar el framework. Desde el proceso de onboarding a poder ejecutar las cosas como se debe, el ReadMe va a jugar un papel fundamental.

Ni me quiero acordar de todas las veces que tuve que estar persiguiendo desarrolladores en el chat o por mail para preguntar cómo era tal cosa o por qué no se había hecho de otra manera tal otra.

Es muy simple, además, que se creen estos gigantescos repositorios y muchas veces se olvide el por qué de muchas cosas. La rotación de gente, las distintas mentalidades y habilidades, todo juega para que un repositorio sin ReadMe se transforme en una Torre de Babel (mi vieja estaría orgullosa por el referención bíblico que tiré).

Y no solo el onboarding, el mantenimiento mismo de un proyecto va a ser mucho más sencillo si está bien documentado. No es sorpresa para nadie, pero muchas veces se considera a este archivito como algo poco importante, no trascendental y nadie se preocupa en hacerlo. Al mediano o largo término, esto siempre vuelve como un grave error.

Y ahora otra tangente que muchos no consideran: Los recruiters. Así es. Cuando apliquen a un proyecto, muchas veces les van a pedir sus repositorios para ver de qué están hechos. Y si, los recruiters muchas veces no entienden casi nada de lo que ven, pero es también cierto que cuentan con palabras clave que identificar y así distinguir un candidato potable de uno que no para lo que buscan.

Imaginen dos repositorios:

  1. Uno aclara las tecnologías que usa: Selenium, Cucumber, Java, Page Object Model y Maven en su Readme.md.
  2. El otro tiene un ReadMe que dice "Framework para automatizar UI".
La búsqueda era para alguien con Selenium y Cucumber. Por ahí el segundo repo está usando ambas tecnologías. Es más, casi seguro lo está haciendo! Pero no lo aclara... y el cerebro del recruiter se vuelca al primero.

Quizás el segundo repo era mejor! Quién sabe... pero esta diferencia mínima marcó la ventaja para el primero.

Este punto va muy de la mano con las personas que me dicen "pero el repositorio es para mi nada más, no hace falta que me preocupe en hacer un ReadMe!". El repositorio NUNCA es para vos nada más. Pensalo...

Conclusión


Hoy les quería hablar de la importancia de un buen Readme.md en sus repositorios. De qué ventajas tiene y de qué se trata. Espero que esto los inspire a tener los suyos en regla!

Como siempre les digo... Nunca dejen de aprender!




Publicar un comentario

0 Comentarios