Los archivos readme sirven para comunicar tu proyecto con cualquier otra persona que ingrese a observarlo, por esto mismo es primordial tener un buen archivo que transmita de manera concreta y bien explicada tu código, para esto mismo te vamos a explicar lo primordial que debería tener junto con algunos tips para que sea más sencillo armar tu propio Readme.
Estructura
La estructura o como está formado el readme es uno de los motivos principales por los que un readme puede ser "tachado" como un mal readme, ya que puede faltar información o simplemente estar mal ordenada, nosotros creemos que hay dos partes en la estructura, aquellos datos obligatorios y los que aportan información y ayudan a verse mejor el readme.
Estructura obligatoria:
-
Título: el título es primordial, lo ideal es que sea conciso y pueda dar una idea de qué se trata el proyecto.
-
Tabla de contenidos o índice: un indice en el comienzo del readme ayuda a conocer previamente que vamos a leer.
-
Funcionamiento: en este apartado la idea principal es explicar de forma resumida qué hace nuestro código.
-
Tecnologías empleadas: explicar qué Tecnologías fueron usadas. P.ej. Lenguaje de programación, paquetes, etc.
-
Imágenes y vídeos: imagenes y videos sobre el funcionamiento, un logo, una explicación gráfica del funcionamiento siempre ayudan a comprender mejor el funcionamiento.
-
Manual de instalación y deployment: explicar como se puede ejecutar nuestro código para cualquier persona que lo desee usar.
-
Roadmap: de esta forma podras dar a conocer los siguientes pasos en tu código.
Estructura adicional:
-
Motivación: escribir sobre por qué decidiste realizar dicho proyecto siempre aporta valor al readme y código.
-
Licencias
-
Agradecimientos: nunca está de más dar agradecimientos a todas las personas que apoyaron para que se llegara al resultado deseado en el código.
Como un plus recomendamos siempre colocar la estructura del proyecto ya que permite que el lector pueda entender mejor el orden de las carpetas y códigos. (Recomendamos usar la extensión "project-tree" en Visual Studio Code), se vería de la siguiente forma:
bashexample-tree ├─ .git ├─ .gitignore ├─ img │ ├─ test1.png │ ├─ test2.png │ └─ test3.png ├─ example-code │ ├─ examplecode.py │ └─ examplecode-test.py ├─ examplecode-app.py └─Readme.md
El formato markdown
Ahora que ya sabemos la estructura de un buen readme, vamos a realizarlo. Estoy seguro que en este proceso tendras múltiples dudas sobre el formato, por lo que te explicaremos como darle estilo al texto.
Titulos y subtitulos:
-
"#" Es utilizado para títulos principales.
-
"##" Se utiliza para remarcar subtitulos, de esta forma podremos resaltarlos en nuestra guía al comienzo.
-
"###" La triple almohadilla se utiliza para crear una división en un subtitulo, y que luego en la guía se vea resaltada.
Estilos:
Los distintos estilos de texto nos van a servir para resaltar alguna zona de un texto.
-
"* _" Un solo _ al principio y final del texto que deseemos resaltar convertira todo lo que esté dentro en cursiva, ejemplo _ sample text _ daría como resultado "sample text". Tiene que estar junto sin espacios.
-
"*_ **" Doble _ al igual que en la cursiva nos sirve para aplicar negrita en nuestro texto, como en el siguiente ejemplo ** sample text ** y su resultado sería "sample text"
-
Se pueden usar ambas juntas para obtener el siguiente estilo sample text
-
Con "-" o "1." al inicio de nuestro código podremos realizar una lista, y se vería así
- sample text
Citas de texto:
Puedes realizar una cita de un texto de la siguiente manera:
"> sample text" y su resultado será el siguiiente.
sample text
Cita de código:
Para colocar un fragmento de un código en nuestro readme lo haremos con comillas triples, esto nos resulta útil para explicar una parte de código o enseñar la manera de ejecutarlo. Tendremos que rodear el código con "```" y se verá de la siguiente manera.
sample text
Tip: Colocando el lenguaje que usemos al final de las primeras comillas podremos hacer que el código se pinte tal como lo vemos al escribirlo
Enlaces e imagenes:
Para colocar imagenes o enlaces en nuestro readme se realiza de una manera muy similar.
En el caso de las imagenes tendremos que hacerlo de la siguiente manera
Y para enlaces de la misma manera pero sin colocar "!" al inicio, por lo que se vería así
[alt-text](url a colocar)
Template
Para tú facilidad te dejamos este template para que ayude a guiarte en el proceso de creación de tu readme con una estructura armada para que edites según tu gusto.
También te dejamos algunos ejemplos de Readme que consideramos muy completos de nuestros alumnos: