Cómo documentar en README.md
El código no es lo único que importa a la hora de desarrollar un proyecto, también lo es la documentación para poder entender, continuar desarrollando, re-utilizar y compartir.
Introducción
Existen diferentes formas de documentar nuestro código pero en esta publicación nos focalizaremos en realizar documentación utilizando documentos md.
Para los que no conocen, en lo que es desarrollo web, se ha convertido en una plataforma estándar para la distribución de software, con el objetivo de incorporar la información acerca de otros archivos en un directorio.
Antes de comenzar, es importante conocer algunos TIPs que nos permitirán armar un documento ordenado, limpio y lindo 😉.
Si queremos hacer títulos tenemos que incorporar el # adelante
# Título
Texto que describa lo que queremos contar.## Otro título dentro del anterior
Más información a sumar.
Luego si queremos hacer negrita o cursiva, es muy simple lo que tenemos que hacer es usar el * una o dos veces. Para la negrita **negrita** y para la *cursiva*.
Ahora sí, con estos datos vamos a ver qué debe tener el README.md y qué es importante incorporar. Si quieren saber más sobre cómo hacer un buen documento, les recomiendo que ingresen acá 🚀.
Comenzando
Es importante entender que la documentación no solo nos ayudará a nosotros sino también poder hacer crecer nuestro proyecto, y también trabajar en equipo con personas descentralizadas por el mundo 🌎.
Desde mi punto de vista, el objetivo del README es contestar 4 preguntas:
- ¿Qué es lo que está intentando lograr el proyecto?
- ¿Cómo puedo utilizar el proyecto?
- ¿Cuáles son los pre-requisitos?
- ¿Cómo puedo participar en el proyecto?
El proyecto
Cuando hablamos de qué es lo que queremos lograr, tenemos que ser muy claros y concretos, contar qué es lo que realmente estamos haciendo para que las personas que lo lean les sea fácil 😁 entender.
No hace falta poner mucho texto, con ser concretos e ir al punto alcanza.
Pre-requisitos
Esta sesión consiste en 3 categorías:
- Sistema Operativo: si el producto esta corriendo en un sistema operativo particular, y únicamente corre sobre ese, es fundamental que se aclare para las personas sepan que tiene que tener su entorno.
- Framework: cuál/es son los frameworks que estamos utilizando en el proyecto y el lenguaje.
- Conocimiento: esto es para que los desarrolladores decidan si vale la pena invertir en el aprendizaje de nuevas habilidades para utilizar este proyecto. Muchas veces sucede que los desarrolladores no conocen una tecnología entonces tienen que investigar antes de comenzar.
Instalar
Llega uno de los momentos más importantes de la documentación, en donde necesitamos demostrar cada comando que debe ser utilizado para hacer andar el proyecto.
El objetivo, es dejar todo lo más claro posible para que los desarrolladores puedan simplemente copiar y pegar, resolviendo rápidamente la instalación.
Por lo general, es poco probable que un desarrollador continúe si las instrucciones de instalación no son claras en 5 minutos ⏳.
Ejemplo a sumar dentro:
```console
$ npm install
```Otro ejemplo claro es cuando se requieren variables de entorno dentro de un archivo o hay que generar un archivo de enviroment.
Ejemplo archivo .env:
ADDRESS="localhost"
DBNAME="username"
DBPASS="123456789"
PORT=37000Ejemplos
Es importante demostrar el uso del software con tantos ejemplos como sea posible. Rara vez hay un código de ejemplo único para todos, así que incluya tantos ejemplos como sea posible para permitir que el usuario tenga al menos una ejecución exitosa.
Todos los desarrolladores quieren probar que funciona el software rápidamente o realizar acciones que le permitan validar la utilización del mismo.
Segunda parte
Ya tenemos nuestra documentación inicial construida, podemos lanzar nuestro producto de esa forma y no tendríamos problemas 🎯.
Pero ahora empiezan aparecer las preguntas de los desarrolladores quienes quieren saber cómo funciona, qué tiene dentro, etc.
Para poder responder estás preguntas, es muy importante brindar la información simple, fácil y bien esquemática.
Organizar el contenido
Uno de los temas más importantes de un README, es poder organizar el mismo a través de tabla de contenidos, y de esta manera las personas podrán visualizar el orden y poder hacer click para poder llegar hacía donde está dicha información.
Para hacer una Tabla de Contenidos, lo que tenemos que hacer es lo siguiente:
# Tabla de Contenidos
1. [Introducción](#introduction)
2. [Requerimientos](#requirements)
3. [Instalación](#Instalación)
4. [Documentación](#doc)
5. [Equipo de Trabajo](#team)
6. [Conclusión](#end)## Introducción
Contenido a desarrollar...## Requerimientos
Contenido a desarrollar...## Instalación
Contenido a desarrollar...## Documentación
Contenido a desarrollar...## Equipo de Trabajo
Contenido a desarrollar...## Conclusión
Contenido a desarrollar...
Es muy importante que respetemos los # los cuales nos van a dar el formato de título y el orden. La tabla de contenido tiene un solo # y el resto de los contenidos dos ##.
Si hemos desarrollado un GRAN proyecto, el cual contiene una base de datos o varios archivos que son objetos y están relacionados, la mejor forma es brindar un gráfico el cual pueda esquematizar rápidamente cómo funciona.
Para realizar esto dentro de un README.md hay varias formas y siempre va a ser dependiendo lo que querrámos hacer. Veamos cada una de las opciones posibles y vemos cómo las aplicamos:
1) Base de datos
Si queremos mostrar cómo está desarrollada una base de datos relacional, la mejor forma es construir una imagen e importarla. Ahora ustedes seguramente se deben estar preguntando:
¿Por qué tengo que irme de Git para armar esto?
La respuesta es mágica y viene al pie hacía ustedes. NO hace falta irse de Internet ni de Git, pueden llamar a Draw.io que permite vincular con GitLab y/o GitHub 😉.
Formas de utilizar diagrams:
Recuerden que al iniciar el proyecto tienen que vincularlo con el proyecto que tienen ustedes.
Ejemplo:
2) Diagrama de Relaciones
Una forma de mostrar un diagrama básico de relaciones puede ser usando código para el README.md y que él mismo se encargue de construirlo cuando una persona lo lea.
¿Cómo hacemos aparecer esté gráfico?
Es más fácil de lo que parece, y simplemente debe poseer al comienzo:
```mermaid
graph TD;Y al final del mismo:
```Veamos cómo quedaría:
```mermaidgraph TD;
client-->client_profile;
client-->customization;
client-->country;
client-->language;
client-->zone;
client-->section_client;
layout-->section_client;
section-->section_client;
content-->section_client;
section_client-->section_extension;
content-->section_extension;
extension-->section_extension;
```
3) Diagrama de Clases
Ya tenemos desarrollado diferentes diagramas y ahora podríamos pensar en armar un gráfico que muestre un diagrama de clases.
Imagino que en este momento deben estar preguntándose cómo puede ser que se pueda hacer esto en README.md.
Bueno, no se preocupen que es realmente tan fácil como el Diagrama de Relaciones:
```mermaid
classDiagram
Class01 <| — AveryLongClass : Cool
Class03 * — Class04
Class05 o — Class06
Class07 .. Class08
Class09 → C2 : Where am i?
Class09 — * C3
Class09 — |> Class07
Class07 : equals()
Class07 : Object[] elementData
Class01 : size()
Class01 : int chimp
Class01 : int gorilla
Class08 ←> C2: Cool label
```Generando tablas
Algo muy común en proyectos de desarrollo es necesitar hacer tablas que permitan mostrar información.
Ejemplo: servicios / APIs para entender qué hace y la información que recibe y devuelve.
Un ejemplo de una tabla para mostrar los campos que recibe un servicio web:
Entonces ahora que vemos una tabla en el README.md veamos cómo lo hacemos:
| **Name** | **Description** | **Data Type** |
| — — | — — | — — |
| name | Name of the client | String |
| cname | CNAME | String |
| url | URL’s to access to the client | String |
| title | Title of the project | String |
| country_id | Id of the country associate to the table country | Integer |
| zone_id | Id of the zone associate to the table zone | Integer |
| language_id | Id of the language associate to the table language | Integer |
| ssl | SSL security if it’s available must be in 1 or 0 disable | TinyInt |
| logo | Logo name locate in your images directory | String |
| twitter_account | Name of your twitter account without https://www.twitter.com/ | String |
| facebok_account | Name of your facebook account without https://www.facebook.com/ | String |
| google_analytics | Alphanumeric reference for your Google Analytics | String |
| facebook_app_id | Facebook App Id | String |
| facebook_secret | Facebook Secret | String |
| security_endpoint | Url of your endpoint | String |
| status | If the client it’s available set in 1 or 0 for disable | TinyInt |Listo, tenemos toda la información necesaria para poder armar nuestra documentación en README.md.
Espero que les sirva y cualquier duda o consulta estoy a disposición 😎.
