La documentación de Discourse se está revisando y editando actualmente para alinearse con esta guía de estilo. No todos los temas de documentación coinciden actualmente con esto; estamos trabajando para lograrlo lo más rápido posible.
Esto se considera un documento vivo que guía cómo se escribe y formata la documentación de Discourse. Este tema se mantendrá actualizado según sea necesario. Si tienes dudas sobre alguno de los principios aquí, publica en el tema para discutir los detalles específicos.
El principio rector detrás de esta guía de estilo de documentación es considerar a tus lectores y sus necesidades al escribir documentación: ¿qué quieren lograr? ¿Cuál es tu objetivo al proporcionar el contenido?
Lista de verificación rápida al implementar la guía de estilo:
- El bloque de metadatos está presente y es correcto.
- El título está orientado a la acción.
- Todos los títulos usan mayúscula inicial en la oración.
- Se utilizan las etiquetas y categorías correctas.
- El documento está estructurado lógicamente.
Al completar un documento, revísalo para asegurarte de que se cumplan todos esos criterios.
Ten en cuenta estas pautas de formato de texto:
Información de metadatos
- El documento debe pertenecer a una y solo una de las siguientes categorías:
- Uso de Discourse
- Guías generales para usuarios en tareas no administrativas
- Gestión del sitio
- Configuración, plugins, contenido y administración general del sitio
- Integraciones
- Guías para integrar otras plataformas con Discourse
- Clientes alojados
- Guías que solo son relevantes para clientes alojados
- Autoalojamiento
- Guías que solo son relevantes para sitios autoalojados
- Guías para desarrolladores
- Guías técnicas para desarrollar sobre Discourse, incluyendo la creación de temas, componentes de temas y plugins
- Contribución
- Guías para contribuir al proyecto de código abierto de Discourse
- Uso de Discourse
- El documento debe pertenecer a una y solo una de las siguientes etiquetas / tipos de documento:
#how-to#explanation#reference#tutorial
- El documento puede tener cualquier otra etiqueta aplicable, con un máximo absoluto de 5 etiquetas en un solo documento.
Bloque de metadatos
Todos los documentos deben tener un bloque en la parte superior que incluya una breve explicación de qué trata el documento, así como cualquier otra información relevante, como los requisitos de nivel de usuario, si se requiere acceso a la consola o cualquier otra cosa. Esto se formateará en una cita sin un encabezado encima. Aquí tienes un ejemplo de cómo debe verse:
Esta es una guía para describir todas las configuraciones ocultas del sitio disponibles, cómo habilitarlas y por qué podrías querer ajustarlas.
Nivel de usuario requerido: Administrador
Acceso a la consola requerido
Títulos y encabezados
- Haz que los títulos del documento estén orientados a la acción.
- Incorrecto: “Cómo habilitar títulos automáticos para hilos de chat”
- Correcto: “Habilitar títulos automáticos para hilos de chat”
- Los títulos del documento no deben ser demasiado largos.
- Para temas de tipo ‘how-to’, haz que el título esté orientado al objetivo.
- Todos los títulos deben ser específicos y únicos.
- No uses puntuación ni caracteres especiales en los títulos del documento, excepto las comas.
- No incluyas emojis en los títulos del documento.
- Usa mayúscula inicial en la oración para títulos y encabezados; es decir, solo la primera palabra comienza con mayúscula, junto con nombres propios y cualquier otra palabra que normalmente llevaría mayúscula.
- No uses signos de ampersand (&) en los encabezados; en su lugar, usa la palabra completa (“y”).
Pautas generales de redacción, tono y gramática
- Usa la voz en segunda persona al referirte a las personas que leen el documento; es decir, usa “tú”, no “nosotros”.
- Usa la voz activa tanto como sea posible.
- Incorrecto: “el botón debe ser clicado”
- Correcto: “clic en el botón”
- Define las siglas y abreviaturas cuando se usen por primera vez; si es necesario, proporciona un enlace externo que ofrezca más información.
- Usa oraciones cortas y divide el texto usando párrafos, encabezados y listas más cortos.
- Puedes usar
**negrita**y cursiva para enfatizar frases o palabras clave, pero no abuses de ellas. - Evita usar jerga o términos técnicos sin explicaciones; si tienes dudas, es mejor explicar.
- Usa capturas de pantalla al describir una interfaz visual, como un elemento de la IU.
- No documentes ni intentes revelar futuras funciones, productos o servicios de Discourse a menos que esté explícitamente permitido.
- Usa palabras de transición como por lo tanto, aunque y además.
- Usa contracciones comunes: es, tendrás, eres, estamos, vamos.
- Infiere la atemporalidad en la documentación; evita palabras como pronto, nuevo, ahora, más reciente, etc., que pronto se vuelven irrelevantes.
- No atribuyas cualidades humanas al software o hardware.
- Ejemplo: “Si pasas un entero a esta API, se enojará y lanzará un error”.
- Ejemplo: “Nuestro amigable y ambicioso bot de IA ayudará a resolver todos tus problemas”.
- Al citar texto (incluido de la IU de Discourse), usa “comillas”.
- Al citar una URL, usa
comillas invertidas. - Al usar un dominio de ejemplo, usa
discourse.ejemplo.com. - Si resulta útil, puedes usar emojis al inicio de un párrafo para resaltarlo. No uses más de dos o tres de estos en un solo tema. Algunos emojis de ejemplo que puedes usar:
- - Una nota informativa
- Anuncio o aviso
- Un mensaje de advertencia
- Información muy importante
- Evita:
- Metáforas o humor innecesarios.
- Referencias culturales y regionales.
- Dictar u ordenar procedimientos con un tono condescendiente; por ejemplo, Debes hacer clic en Publicar o Necesitas hacer clic en Publicar.
- Ser excesivamente educado. Por ejemplo, Por favor, haz clic en Publicar.
- Usar puntos de exclamación a menos que sea absolutamente necesario.
- Mayúsculas en palabras donde no son necesarias.
- Uso excesivo de las mismas frases y pronombres.
Para documentación de usuarios finales:
Mantén un tono amigable e informal, con un enfoque en ser claro y conciso de manera informada. Ve al grano rápidamente. Explica los términos técnicos, pero ten cuidado de no ser condescendiente. Para asegurar la claridad, comienza especificando brevemente el contexto del tema actual.
Para documentación de desarrolladores y técnica:
Mantén un tono directo y preciso. Usa el mismo tono que para la documentación de usuarios, pero puedes asumir un mayor nivel de conocimiento técnico en tus lectores.
Estructura
- Ve al grano rápido: comienza con lo más importante.
- Incluye palabras clave importantes al principio del documento.
- Haz que las opciones del lector y los siguientes pasos sean obvios.
- Siempre usa marcado ligero para escribir documentación (esto ya está integrado en Discourse con Markdown-it).
- Referencia de uso: https://markdown-it.github.io/
- Organiza tu documentación en un flujo lógico: comienza con una visión general, seguida de secciones detalladas y un resumen o conclusión si corresponde.
- Usa encabezados y subencabezados para estructurar tu contenido, facilitando que los lectores escaneen y encuentren información específica; usa una jerarquía descendente en los encabezados, comenzando con h2, y no saltes niveles.
- Proporciona enlaces a temas o secciones relacionadas dentro de tu documentación; esto ayuda a los usuarios a encontrar información adicional sin búsquedas innecesarias.
Enlaces
- Usa texto significativo en los enlaces.
- A menos que el formato de la URL sea importante o instructivo, no uses una URL como texto del enlace; en su lugar, usa el título de la página o una descripción de la página.
- Enlaza a sitios y fuentes externos en lugar de citar o reescribir documentación existente.
- Asegúrate de que los sitios a los que enlazas sean de alto estándar y calidad.
- Si el enlace descarga un archivo, menciónalo explícitamente; también indica el tipo de archivo que se descarga y una estimación aproximada del tamaño del archivo.
Código en la documentación
- Usa bloques de código con resaltado de sintaxis específico del lenguaje cuando sea posible para ejemplos grandes de código.
- Si no es autoexplicativo, introduce un ejemplo de código con una oración introductoria que presente el ejemplo que sigue; si tienes dudas, es mejor explicar.
- Los ejemplos de código deben seguir las mejores prácticas para escribir código en el lenguaje de programación relevante.
- Usa código en línea para expresar atributos básicos de código o cuando no sea necesario un bloque de código completo, como:
- Nombres y valores de atributos
- Nombres de clases
- Nombres de utilidades de línea de comandos
- Tipos de datos
- Nombres de variables de entorno
- Nombres de archivos, extensiones de archivo y rutas
- Carpetas y directorios
- Verbos HTTP, códigos de estado y valores de tipo de contenido
- Nombres y valores de parámetros de consulta
- Entrada de texto
- Cuando uses un marcador de posición en ejemplos de código, comandos u otro texto, incluye una explicación de lo que representa el marcador de posición.
- Escribe una explicación la primera vez que uses el marcador de posición; si hay múltiples marcadores de posición o pasos después del primer uso de ese marcador, puedes explicarlo nuevamente.
- Proporciona una forma fácil para que los usuarios o desarrolladores copien y ejecuten el código.
- Muestra la salida esperada, ya sea en una sección separada después del ejemplo de código o usando comentarios de código dentro del ejemplo de código.
- Escribe código seguro; nunca codifiques contraseñas, claves de API o información segura en el código.
Procedimientos y guías paso a paso
- Formatea los procedimientos de manera consistente para que los lectores puedan encontrarlos fácilmente al escanear.
- Usa una entrada numerada separada para cada paso.
- Incluye acciones que finalicen un paso, como botones de Aceptar o Aplicar.
- Si la instrucción aparece en la misma IU donde ocurre la acción, generalmente no es necesario proporcionar detalles de ubicación.
- Si necesitas asegurarte de que el lector comience en el lugar correcto, proporciona una frase breve al inicio del paso.
Accesibilidad e inclusión
- Usa capturas de pantalla, diagramas o videos cuando agreguen valor, especialmente para explicar pasos complejos o mostrar partes de una interfaz.
- Las imágenes deben usarse para respaldar la información textual, no para reemplazarla.
- Siempre usa atributos
altpara imágenes. - Proporciona siempre subtítulos o transcripciones para videos.
- Usa GIFs solo si puedes completamente explicar el contenido en texto.
- Elige imágenes simples y recorta detalles innecesarios.
- Usa lenguaje sencillo y evita figuras retóricas o modismos que podrían no ser universalmente entendidos.
- Considera que tu documento se usará en una multitud de dispositivos.
- Usa lenguaje neutro en cuanto al género. No uses él, lo, su, ella, le, su al referirte a personas; para evitar pronombres, puedes:
- Reescribir usando la segunda persona (tú).
- Reescribir la oración para que tenga un sustantivo y pronombre plural.
- Usar las palabras persona o individuo.
- Usar artículos el, un o una en lugar de un pronombre.
- Usar un pronombre plural como ellos, su o les, incluso si se refiere a un solo individuo.
- Cuando escribas sobre una persona real, usa los pronombres que esa persona prefiera.
- Sé inclusivo con la identidad de género, raza, cultura, religión, discapacidad, edad, orientación sexual y clase socioeconómica; incluye una amplia variedad de profesiones, culturas, entornos educativos, localidades y contextos económicos en los ejemplos.
- Evita contenido politizado; en casos donde se deba incluir contenido político, mantente neutral.
- No hagas generalizaciones sobre personas, países y culturas, ni siquiera generalizaciones positivas o neutrales.
- No escribas contenido prejuicioso y discriminatorio contra ninguna comunidad, especialmente minorías.
- Evita términos cualitativos relacionados con eventos históricos.
- Evita usar términos y metáforas asociados con violencia y acciones militares.
.
). Buen punto sobre la inconsistencia. No estoy seguro de cuál adoptaremos, pero definitivamente nos aseguraremos de elegir uno y ceñirnos a él. 