Guía de estilo de Unraid Docs
El SO Unraid está moldeado por el equipo de LimeTech y la comunidad de Unraid. Nuestra documentación busca ser completa, precisa y actual. Como nuestros usuarios provienen de diversos orígenes en todo el mundo, esta guía establece la base para una escritura consistente y clara en toda la documentación de Unraid.
Convenciones de escritura
Estilo y tono
Nuestro tono busca un equilibrio entre amistoso y formal, con el objetivo de obtener un contenido detallado y preciso con el que los usuarios puedan identificarse.
- Utilice instrucciones formales y directas cuando la acción esté establecida y no deje lugar a desviaciones.
- Use un tono conversacional y explicativo al proporcionar contexto o escenarios para hacer que el contenido sea más accesible.
Como contribuyente, considere el contexto y la audiencia al elegir su tono.
Debido a que el SO Unraid tiene una audiencia global, evitamos la jerga, la jerga técnica o los modismos. Estos pueden confundir a los hablantes no nativos de inglés y dificultar el proceso de traducción.
Audiencia: Escribe para todos los niveles
Nuestros lectores van desde expertos en Linux que entienden los sistemas internos hasta principiantes que exploran Unraid por primera vez.
Escriba de manera clara e inclusiva para que tanto expertos como novatos puedan seguir sin problemas.
El método ABC: precisión, brevedad, claridad
Priorizamos:
- Precisión: Asegurar que el contenido sea correcto y completamente probado.
- Brevedad: Ser conciso sin sacrificar detalles necesarios.
- Claridad: Usar un lenguaje sencillo y estructurar el contenido para facilitar su comprensión.
Sintaxis
Los documentos de Unraid utilizan el formato Markdown combinado con estilos de texto específicos para que los usuarios puedan identificar rápidamente los elementos del interfaz y navegar por el WebGUI.
| Tipo de elemento | Convención de estilo | Sintaxis de Markdown | Ejemplo / Descripción |
|---|---|---|---|
| Nombre de la opción o botón | Negrita | **texto** | Seleccionar Hecho |
| Valor de entrada del usuario | Cursiva | *texto* | Introducir un valor de 50gb |
| Ruta de navegación | Negrita + cursivas; use → | ***nav1 → nav2*** | Configuraci ón → Configuración de Disco |
| Etiqueta de pestaña | Negrita | nombre_de_pestaña | Nombre de una pestaña para seleccionar |
| Etiqueta de casilla de verificación | Negrita | etiqueta_de_casilla | Etiqueta de una opción de casilla de verificación |
| Opción de menú desplegable | Cursiva | opción_de_desplegable | Opción seleccionable dentro deun menú desplegable |
| Título de diálogo | Encabezado 3 | ### Título del Diálogo | Título para ventanas de diálogo emergentes |
| Texto de tooltip | Cursivas en línea | texto de tooltip | Explicación breve que se muestra al pasar el ratón |
| Elemento del menú | Negrita + cursiva | Menú → Submenú → Elemento | Navegación a través de menús anidados |
| Salida de CLI y sistema | Monoespacio (código en línea) | `texto` | Navega a http://tower.local |
| Mensaje de error | Monoespacio (código en línea) | `Error: mensaje` | Cadenas o registros de error exactos |
| Título del documento | Encabezado 1 | # Encabezado | (se presenta como) <h1>Encabezado</h1> |
| Sección del documento | Encabezado 2 | ## Encabezado | (se presenta como) <h2>Encabezado</h2> |
| Subsección del documento | Encabezado 3 | ### Encabezado | (se presenta como) <h3>Encabezado</h3> |
Cada nivel de encabezado 2 (##) y menor aparece en la barra lateral de la Tabla de Contenidos (TOC) para facilitar la navegación.
Formato para listas y tablas
El uso eficaz de elementos estructurados, como listas y tablas, mejora la claridad de la información, facilita la comprensión y soporta referencias rápidas.
Listas
Las listas ayudan a los usuarios a asimilar, recordar y seguir puntos clave o pasos. Hay dos tipos principales, cada uno con casos de uso claros:
-
Listas no ordenadas (viñetas): Usar para agrupar elementos relacionados sin implicar un orden. Ejemplo: "Lista de herramientas comunes de Unraid OS."
-
Listas ordenadas (numeradas): Usar para mostrar una secuencia o procedimiento requerido. Ejemplo: "Para iniciar el array..."
- Trate de introducir la lista con una frase clara finalizando en dos puntos.
- Utiliza de 4 a 6 elementos como máximo en una lista no ordenada para facilitar el escaneo y la memorización. Las listas más largas pueden ser mejor como una tabla.
Tablas
Las tablas son una excelente manera de organizar datos relacionados agrupando la información en filas y columnas, lo cual facilita una comparación más rápida y precisa.
- Utilice tablas para múltiples puntos de datos relacionados que se beneficien de una comparación lado a lado.
- Evite las tablas con solo 1 o 2 celdas; en su lugar, utilice listas con viñetas o frases.
- Introduzca la tabla con una frase que explique su propósito y contenido.
Abreviaturas, acrónimos y siglas
Para reducir la confusión a los lectores, siga estos principios respecto a las abreviaturas:
- Abreviaturas son formas abreviadas de palabras que generalmente son innecesarias en los documentos de Unraid a menos que sean universalmente reconocidas.
- Acrónimos crean nuevas palabras a partir de las iniciales de otras palabras (por ejemplo, RAID).
- Siglas usan iniciales que se pronuncian individualmente (por ejemplo, OS, ZFS).
Recomendaciones:
- Prefiera acrónimos o siglas preexistentes bien conocidos que sean familiares para su audiencia.
- Evite crear nuevas abreviaturas solo por el hecho de ser breve.
- Siempre deletrea acrónimos o siglas poco comunes la primera vez que se utilizan, seguidos de la abreviatura entre paréntesis. Ejemplo: Disco de Máquina Virtual (VMDK)
Hipervínculos a otros documentos o sitios
El enlace estratégico permite a los lectores explorar temas relacionados y mejora su comprensión. Usa estas pautas para una hipervinculación práctica y accesible.
Pautas para el texto del enlace
- El texto del enlace debe describir claramente el destino, ayudando a todos los lectores a entender el propósito del enlace.
- Evite textos de enlace vagos como "Haga clic aquí" o "Leer más", ya que carecen de contexto.
- Evite usar URLs visibles como texto de enlace en línea.
Formato de enlaces
- Utilice enlaces en línea de Markdown:
También puedes consultar nuestra [guía de inicio](../unraid-os/getting-started/quick-start-guide.mdx).
- Siempre enlace al recurso más relevante y autorizado disponible.
Añadiendo terminología del glosario
Unraid Docs utiliza un sistema de glosario centralizado para garantizar la consistencia y accesibilidad de los términos técnicos. Las entradas del glosario se mantienen en el archivo glossary.yaml ubicado en el directorio raíz.
Para agregar o actualizar un término:
- Edite
glossary.yamlusando la siguiente plantilla:
TérminoGlosario:
término: Nombre para Mostrar
def: Texto completo de la definición.
link: <a href="https://example.com">Enlace detallado opcional</a>
-
Para agregar funcionalidad de ayuda emergente, haga referencia al término en la documentación usando la sintaxis:
%%Término|TérminoGlosario%%...donde el lado izquierdo de la barra es el texto que desea que se muestre, mientras que el lado derecho es la entrada de término correspondiente del archivo YAML.
-
- La página del glosario se actualizará automáticamente para incluir nuevos términos.