Guías de escritura

Creación de un archivo de guía

Para empezar a escribir una guía, necesitas crear un archivo con la extensión .mdx. Necesitas crear este archivo dentro del directorio /content/docs/en a partir de ahí, dependerá de la sección en la que quieras crear la guía, por lo que podrás decidir en qué carpeta debes colocarla.

Supongamos que quiero crear una guía de fundamentos de Java, la colocaría en /content/docs/en/guides/java-basics. Tendrás que investigar un poco para decidir dónde quieres colocarla.

El Frontmatter es el metadato de tu guía; indica a nuestro sitio web cómo debe mostrarse la guía. Esto debe ir en la parte superior del archivo, que empieza con --- y termina con ---.

Aquí un ejemplo:

---
title: "Básicos de Java"
description: "Aprende lo básico para programar con Java"
authors:
    - name: "Tu nombre"
      url: "https://tupaginaweb.com"
---

Como puedes ver, es bastante autoexplicativo, solo tienes que rellenar los detalles correspondientes a tu guía específica. Si no tienes una URL que quieras enlazar, simplemente no escribas esa línea completa. Adicionalmente, la sección de autores es opcional, así que si no quieres añadirla, puedes omitirla, aunque te animamos a hacerlo y darte crédito.

La identación en el frontmatter es importante, así que asegúrate de mantenerla consistente con el ejemplo.

Estructura del contenido

Debes estructurar el contenido de tu guía de forma clara y organizada. Aquí tienes algunos consejos para hacerlo:

• Introducción: Empieza con una visión general del tema y lo que el lector puede esperar aprender.
• Prerequisitos: Enumera los requisitos previos o conocimientos necesarios que el lector debería tener antes de empezar la guía.
• Instrucciones Paso-a-Paso: Divide el contenido en pasos claros y accionables. Usa encabezados y subencabezados para organizar la información.
• Ejemplos de código: Incluye fragmentos de código para ilustrar los puntos clave. Asegúrate de explicar cada ejemplo a fondo.
• Conclusión: Resume los puntos principales y anima al lector a profundizar más o a poner en práctica lo que aprendió.

Si estás escribiendo una sección muy grande, deberías dividirla en varias páginas para que al lector le resulte más fácil asimilar la información. ¡Nadie quiere leerse un muro enorme de texto de una sola vez!

Cuando escribimos guías, también deberíamos pensar en cómo lo asumirá la gente, muchas personas prefieren ojear el contenido en lugar de leerlo en detalle. Por eso es mejor dividir la información en varias páginas, de modo que al lector le parezca una cantidad menor de contenido. Además, considera usar viñetas, listas enumeradas y otras técnicas de formato para que el contenido sea más fácil de escanear.

Formato

Usamos Markdown para formatear nuestras guías. Aquí tienes algunos puntos clave a tener en cuenta:

• Usa encabezados (#, ##, ###) para organizar tu contenido.
• Usa viñetas y listas enumeradas para mayor claridad.
• Use code blocks (```) for code snippets.
• Usa links de referencia a otras guías o recursos externos.

Este es el mismo tipo de formato que verás en la mayoría de sitios web de documentación y también en plataformas de redes sociales como Discord.

También puedes usar un Callout para resaltar información importante o consejos. Usa la siguiente sintaxis:

<Callout>
    Esto es un mensaje Callout.
</Callout>

Puedes cambiar el color del callout añadiendo un atributo type Por ejemplo:

<Callout type="info">
    Esto es información del callout.
</Callout>

Tipos disponibles: info, warning, error, y success

Conclusión

¡Eso es todo! Ahora eres un master escribiendo guías. Solo recuerda: no hace falta que tu inglés sea perfecto, escribe la guía tal y como le explicarías el tema a alguien y no dudes en pedir feedback o ayuda si lo necesitas.

¡Feliz escritura!