Documentación
Bien, hasta ahora usted ha aprendido sobre; electromagnetismo, generación y protección de electricidad, procesadores, controladores, ARM, memoria, codificaciones, entre otros.
Pero no sirve de nada saber algo si no se puede documentar bien y transmitir ese conocimiento. Si la humanidad ha podido progresar es por la evolución de nuestros propios sistemas de documentación y transmisión de información a futuras generaciones.
Por eso mismo usted debe saber como documentar algo de forma correcta.
Aclaro lo siguiente; cuando hablamos de documentación nos estamos refiriendo a la capacidad de una persona de transmitir información de forma clara y concreta. Una documentación no necesariamente es un archivo PDF o una publicación extremadamente larga (como la presente), puede ser incluso un email, una carta documento o hasta un mensaje de texto.
Escritura y expresividad
La escritura correcta es absolutamente esencial debido a que le permitirá a sus lectores poder entender correctamente y a su vez evitar malentendidos que pueden derivar en problemas.
Por lo tanto siempre debe considerar los siguientes puntos;
- Al empezar una escritura, en el saludo (que debe estar siempre al principio) como en la despedida no va ni punto ni nada luego de la frase, va una coma.
- Luego del saludo va lo más importante del cara al destinatario. No importa que es más importante para nosotros, si no lo que es más importante para la otra persona.
- Salvo que; ó esté aclarado, descrito o que ambas partes estén de acuerdo, evitar el “en tiempo y forma”. Debido a que es total y absolutamente subjetivo que es “en tiempo y forma”.
- Los nombres de las áreas (de una organización, documento, empresa, etc) tienen que ir en mayúsculas, al igual que los nombres personales.
- En el español no van los días de la semana en mayúsculas, en el inglés sí.
- No existe “en referente a” si no que es “en referencia a”.
- Entre cada párrafo va una línea de separación.
- Las palabras en otros idiomas van en cursiva, no entre comillas dobles o simples.
- Evitar siempre hacer críticas, en cambio “proponer mejoras” sin hacer que el destinatario sienta que lo que hizo no tiene valor (aunque esté todo mal, valor por el intento al menos).
- Salvo que sea “mea culpa”, luego es mejor usar críticas despersonificadas.
- Tanto en una sola oración como en varias, primero va lo que se quiere enfatizar.
- Usar lenguaje descriptivo y positivo, evitar oraciones con “no” como declaración de que cosas no se tienen que hacer, salvo que sean de vida o muerte. El general del ser humano lo toma a mal.
- Nadie es una eminencia, todos somos humanos y los errores son parte de nuestro día a día. Ergo, no trate la información de este post como palabra santa ni usted escriba o se exprese como si lo fuera.
Formato
No sirve de nada que uno tenga la mejor prosa (forma que toma naturalmente el lenguaje para expresar los conceptos, y no está sujeta, como el verso, a medida y cadencia), expresividad y dialecto si la información no es accesible.
Por eso mismo, el formato se divide en dos categorías;
-
Accesibilidad de almacenamiento
La accesibilidad de almacenamiento describe la capacidad de que la información pueda ser accedida para luego ser leida sin impedimiento alguno.
-
Accesibilidad de lectura
La accesibilidad de lectura describe la capacidad del lector de entender la información que se le da sin importar su nivel académico y de educación.
Por lo tanto, y considerando las dos categorías anteriores, podemos determinar una serie de puntos a cumplir;
- La información debe estar en un formato de almacenamiento que le permita al lector poder acceder al mismo sin importar; programa usado para leer, sistema operativo, protocolo utilizado y año de creación/lectura.
- Si la información presentada y entregada tiene imágenes, en cumplimiento con los dos puntos anteriores, las mismas deben estar embebidas dentro de la información y no separadas del documento.
- La información y sus medios audiovisuales multimedia (imágenes, videos, sonido, etc) embebidos deben utilizar un formato de almacenamiento que permita al lector la accesibilidad aunque una parte de la información se corrompa o borra.
- La información debe estar presentada de una forma que se aclare todo concepto utilizado, sin dar nada por conocido del lector más allá de que sabe leer. Todo lo demás se debe considerar que no lo conoce.
Luego de lo anteriormente mencionado, ¿existe un formato digital de archivo que permita todo lo anterior (siempre y cuando uno escriba correctamente)? Sí, prosiga al siguiente sección.
Markdown
Fue creado por John Gruber (1973-XXXX) y Aaron Swartz (1986-2013) en 2004.
Markdown es un lenguaje de marcado que sirve como base para su interpretación en diferentes formatos, debido a esto es usado por páginas/webs muy conocidas como; Reddit (para la creación y edición de comentarios y posts), Github y Gitlab (para los archivos de texto/documentación como los README.md) y tantos otros programas como ‘Pandoc’.
Al ser un lenguaje de marcado, puede ser muy fácilmente leído en crudo (véase; sin tratar) por cualquier humano, y también por diversos programas que lo interpretan en otro formato. El ser de este tipo de lenguaje hace que todo dependa de su sintaxis. El primer programa en hacerlo fue ‘markdown-to-html’ creado en Perl por Gruber.
Sin más dilación, un ejemplo de su uso es esta misma web, todos sus artículos están escritos en Markdown y luego interpetados en HTML con ‘Hugo’.
Website y documentación
- Página principal
https://daringfireball.net/projects/markdown/
Extensión de archivo
Los archivos markdown llevan extesión; “.md” o “.markdown”.
Ventajas
-
Los archivos de markdown, como lenguaje de marcado, son puro texto por lo que son mucho más resilientes que un archivo comprimido (como los “docx”, “odt” que sí, son archivos zip comprimidos) ante corrupciones, etc.
-
Al ser puro texto, sin aditivos, pueden ser leídos por cualquier sistema operativo y cualquier programa, evitando así problemas de compatibilidad de cualquier tipo. Podes usar desde un simple block de notas, micro, nano, vim, vi hasta un IDE entero.
-
Al ser puro texto, y ser interpretados por un programa externo que genera el archivo final en otro formato (como; “pdf” u otro tipo), se puede mantener una misma fuente (el propio archivo markdown) y seguir generando versiones nuevas.
-
Al ser puro texto, es mucho más dificil que se corrompa y se pierda todo el archivo, esto debido a que los sistemas operativos (y muchos programas) cuando escriben texto lo hacen guardando en tandas de caractéres (esto puede variar, pero generalmente suele ser así). En cambio cuando es un archivo binario se escribe por bits y si se inerrumpe el proceso puede corromper la estructura completa.
-
Puede contener imágenes de varias formas; en codificación base64, en referencia local o de internet. Esto permite que una imagen codificada en texto pueda ser embebida dentro del archivo markdown sin necesidad de ser almacenada como un binario (como hacen “odt” y “docx”).
Diferencias entre “lenguaje de marcado” y “formato”
- Formato;
Un formato, en el contexto que nos ocupa de los archivos, lleva una estructura de datos definida, con un lenguaje (binario o de texto) específico, una codificación específica (como se interpreta cada caracter). Generalmente la estructura está pensada y organizda por cantidad de bytes.
- Lenguaje de marcado;
Solo texto plano, codificado en UTF-8 y en cualquier idioma humano. Es un programa externo el que se encarga de interpretarlo para su correcta visualización.
Estándares y visualizadores
Debido que un texto en Markdown debe ser interpretado para luego ser convertido en otro formato diferente, puede haber pequeñas discrepancias entre como interpreta cierta ‘sección’ dependiendo de si soporta o no esa parte de la especificación.
Los estándares son definidos por la IETF (Internet Engineering Task Force) y aprovados para la publicación por el IESG (Internet Engineering Steering Group).
Estándar base
Es el propio markdown original creado en el 2004.
- https://daringfireball.net/projects/markdown/syntax
Tiene su estándar internacional en el RFC-7763 :
- https://datatracker.ietf.org/doc/html/rfc7763
Estándares extendidos
Son estándares extendidos sobre el base, en algunos casos incluso modificándolo.
Tiene su estándar internacional en el RFC; https://datatracker.ietf.org/doc/html/rfc7764
Existen varios como, pero no limitados a;
- CommonMark
Es un estándar creado por las principales webs y programas del mundo que utilizan markdown para expandir el estándar base con nuevas funcionalidades.
Fue creado originalmente por John de ‘Pandoc’, David de ‘Meteor’, Vincent de ‘Github’, Neil de ‘Reddit’, Benjamiin de ‘Stackoverflow’ y Jeff de ‘Discourse’.
- GitHub Flavored Markdown
Es una extensión de CommonMark por parte de GitHub para añadir más seguridad a las páginas HTML que genera el motor de esa misma web.
Principalmente la diferencia es que CommonMark soporta varios tipos de entrada, mientras que GFM es mucho más estricto y soporta una.
- PHP Markdown Extra
Es una extesión de PHP sobre Markdown para mejorar aún más el sopporte para código, entre otros. Tiene su base / inspiración también en el utilizado por Python y Ruby.
Añade principalmente;
-
Markdown dentro de HTML.
-
Elementos con los atributos “id” y “class”.
-
Una variante para múltiples líneas de código.
-
Tablas.
-
Listas definidas.
-
Pies de páginas.
-
Abreviaciones.
-
LiaScript
Es una extensión añadida en Elm y TypeScript.
Añade principalmente;
- Animaciones.
- Salida hablada automáticamente.
- Fórmulas matemáticas usando KaTex.
- Diagramas basados en caracteres ASCII.
- Integración nativa con JavaScript.
Sintaxis básica
Acá se contempla y se explica el estándar base definido en el RFC-7763 así como en la definición original.
Textos y párrafos
En Markdown los párrafos no se definen por una ‘nueva línea’ (‘\n’ en los Unix y ‘\r’ en Windows) si no por dos nuevas líneas.
Ejemplo, este texto se interpretará como una sola línea;
El siguiente texto a pesar
de que esté sepaado por una nueva línea en cada una
se interpretará como una continua, debido a que se necesitan dos para separar.
quedando así;
El siguiente texto a pesar de que esté sepaado por una nueva línea en cada una se interpretará como una continua, debido a que se necesitan dos para separar.
Una buena práctica es que pongas el texto de un párrafo separado por una nueva linea luego de una cabecera, lista u otros. La gran mayoría de los intérpretes no tendrán problema en identifcar bien las partes pero por las dudas siempre es preferible.
De igual manera el estándar base especifica que si se introducen dos espacios y luego una nueva línea, el intérprete debe reconocerlo como una línea separada, aunque esto no se aconseja debido a que a la persona no le permite identificar esto rápidamente. Ejemplo de esto que digo es este párrafo, que esta creado de esta manera.
Así mismo en Markdown no se deben utilizar sangrías de tipo alguo.
Cabeceras
En Markkdown las cabeceras son especificadas con el caracter ‘#’. Dependiendo del intérprete tenes entre cuatro (4) y seis (6) títulos y subtítulos.
Cada vez que bajes un nivel (véase añadas un ‘#’) ese título se convierte en subtítulo del anterior y se achica en tamaño.
Por ejemplo;
# Título 1
## Título 2
### Título 3
#### Título 4
##### Título 5
###### Título 6
Una buena práctica es separar el numeral ‘#’ del resto del texto.
Una alternativa para las cabeceras es usar líneas, pero tiene la desventaja que solamente soporta dos títulos y al ser alternativa no todos los intérpretes lo reconocen;
Titulo 1
==========
Título 2
----------
Haciendo este libro/post me dí cuenta de una cosa, GoHugo y otros intérpretes soportan/reconocen hasta un “Título 6”, un número 7 ya no sería reconocido como tal.
Listas
En Markdown hay dos tipos de listas, las ordenadas y las no ordenadas.
Se puede poner texto luego de un punto de la lista pero tiene que ser un nuevo párrafo, de lo contrario no detectara el espacio y lo añadirá todo junto. Si el texto debajo de un item de la lista empieza con tres espacios entonces pasa a estar debajo de ese item con una sangría en el renderizado.
- Listas ordenadas
Se especifica con un número segudo de un punto y espacio. Por ejemplo;
1. Elemento uno.
2. Elemento dos.
3. Elemento 3.
En las listas no ordenadas no importa el número antes del texto, el intérprete debe renderizar en orden ascendente.
Así mismo con tres espacios se puede generar una sub lista;
1. Elemento uno.
2. Elemento dos.
1. Sub elemento uno.
2. Sub elemento dos.
3. Sub elemento tres.
3. Elemento 3
- Listas no ordenadas
Se especifica con un guión ‘-’ y espacio. Por ejemplo;
- Elemento uno.
- Elemento dos.
- Elemento tres.
También se pueden especificar con los caracteres; * y +. Pero se debe tener en cuenta que siempre se debe usar uno solo en toda la lista.
Al igual que con las listas ordenadas, también se pueden crear sublistas.
Negrita o remarcado
Para poner un texto en negrita o remarcado se puede utilizar dos formas;
- Utilizar la palabra o texto entre cuatro (4) astriscos; *
- Utilizar la palabra o texto entre cuatro (4) guiones bajos; _
- Por ejemplo;
**Texto remarcado**
es interpretado como;
Texto remarcado
- Por ejemplo;
__Texto remarcado__
es interpretado como;
Texto remarcado
Si de toda una palabra o frase sin espacios (véase con todos los caracteres juntos), se quiere remarcar solamente unas pocas letras, NO se deben utilizar los guiones bajos si no los asteriscos.
Cursiva
La letra cursiva, también llamada ‘itálica’ (como una mala traducción de ‘Italic’), lleva la misma sintaxis que el negrita/remarcado pero con un número menos.
- Por ejemplo;
*Texto en cursiva*
es interpretado como;
Texto en cursiva
- Por ejemplo;
_Texto en cursiva_
es interpetado como;
Texto en cursiva
Citaciones
Las citaciones son bloques de texto en donde se cita, valga la redundancia, un texto que no es de autoria propia.
Llevan la siguiente sintaxis con el símbolo mayor ‘>’;
> TEXTO A CITAR
que terminará siendo interpretado como;
TEXTO A CITAR
Si el texto a citar tiene varios párrafos, se puede usa un símbolo de mayor como separador entre párrafos.
También puede pasar que se necesite hacer una citación dentro de otra, para la segunda citación se usan dos mayores.
Así mismo las citaciones soportan todo el dialecto dentro, por lo que todo lo que esté ahí será interpetado correctamente. Deberá tener eso en cuenta, ya que se puede tener un Markdown dentro de una citación.
Bloques de código
Acá mezclo una parte del estándar básico con el extendido, ya que este último modifica de forma directa al primero.
Un bloque de código lleva una sintaxis específica, incluso para los espacios y tabuladores, de ahí que una de sus máximas es respetar el texto sin modificarlo. De esto se encarga el bloque de código.
Dependiendo del intérprete utilizado, incluso se puede colorear el código para hacerlo fácilmente legible. En el estándar básico no se especifica el lenguaje utilizado, en el extendido sí.
La sintaxis esta definida por el uso de tres comillas simples: ’ tanto para el inicio como el final.
\ ```[nombre del lenguaje utilizado en el código]
\ ```
Como podes ver, estoy usando la contrabarra, eso le indica al intérprete que no tome como Markdown lo que sigue. Es necesario para poder mostrarle como se especifica el código. Esto se llama ‘caracter de escape’.
- Por ejemplo para un código en BASH (Bourne Again Shell);
\ ```bash
#!/bin/bash
echo “Esto es un código en BASH”
\ ```
renderizado queda como;
#!/bin/bash
echo "Esto es un código en BASH"
Dependiendo del intérprete se reconoce la sintaxis de un lenguaje de programación u otro, y por ende colorea su código o no.
Imágenes
Hay varias formas de especificar una imagen. No está dentro de los dos estándares especificados pero algunos intérpretes son capaces de reconocer una imagen codificada en BASE64 (un sistema de codificación en letras y números para transmitir archivos binarios en red), lo que da la excelente ventaja de poder embeber una imagen dentro de un archivo de texto plano como es el Markdown.
Las formas son;
- Especificando la ruta completa de la imagen en el dispositivo local desde donde se toma el Markdown. Algunos intérpretes son capaces de tomar incluso por posición relativa.
- Especificando la U.R.L. de internet desde donde descargar la imagen. Personalmente no recomiendo esto ya que se está dependiendo de la disponibilidad remota de ese recurso y de que no sea modificado de forma inapropiada por un tercero.
- Codificando la imagen en BASE64. Toda las imágenes dentro de esta web (shyanjmc.com) están embebidas en sus respectivos Markdown de esta forma, ya que Hugo (GoHugo) es capaz de reconocerlo.
Vallamos por partes. En todas la sintaxis es;
Por ejemplo para una imagen de internet voy a elegir la imagen del F-22 Raptor de la wikipedia;
- https://upload.wikimedia.org/wikipedia/commons/4/46/Lockheed_Martin_F-22A_Raptor_JSOH.jpg
Quedando la sintaxis de la siguiente forma;
y quedando así renderizado;
Ahora si se quiere hacer uso de las MAGNÍFICAS ventajas que trae el codificar las imágenes en BASE64 se debe cambiar la sintaxis para especificar que los datos están ahí en el texto mismo;
Simplemente se remplaza “XXXXXXXX” por la codifcación en BASE64 de la imagen. Siguiendo con la imagen del caza F-22 quedaría así, advierto que es una salida larga.
Así mismo se puede usar imágenes en png, jpeg, jpg, etc. La extensión de la codificación en BASE64 dependerá de la resolución y de la profundidad de bits.
Renderizandose así finalmente ;
