Guía de Estilo de Documentación de Fedora

Lo más largo es una documentación de usuario, lo más difícil es comprender. Escriba con brevedad (para el tema) es bueno. La claridad es mejor.

Voz pasiva es el uso del objeto de una sentencia como el sujeto. Por ejemplo

Indican voz pasiva. Reescriba su sentencia para sonar fuerte. Por ejemplo:

A no ser que actualmente esté hablando sobre planes futuros o publicaciones, el tiempo presente es lo mejor.

Demasiado uso de ser hacen sus sentencias débiles. Intente utilizar el verbo del formulario de palabras que ha desviado a cualquier sitio en la sentencia. A menudo puede simplificar abandonando palabras, o utilizar la mejora (dirigiendo o advirtiendo) formulario de la sentencia.

El ingles de EE. UU. es el idioma franco en todo el Fedora Project.

Estructure su artículo con abstracto, tirador, y marcador esencial de AsciiDoc.

La escritura verbosa es intimidante. En su lugar, organice el texto mediante párrafos, viñetas y pasos numerados. Esto ayuda al usuario a comprender el texto rápidamente y, sobre todo, no resulta abrumador. Incluya un breve resumen al principio de un conjunto más largo de párrafos: especialmente después de los encabezados de segundo y tercer orden ("h2" y "h3", "==" y "===" en AsciiDoc), debe seguir una oración o párrafo corto que describa brevemente el objetivo o el tema de los párrafos posteriores, captando la atención del lector y alineándose con sus expectativas.

Escriba con mayúscula únicamente el título del artículo.

No escriba con mayúscula las palabras en el título de su artículo ni en ningún encabezado, excepto los nombres propios.

Utilice negrita solo para una frase o afirmación extremadamente importante.

Elementos de la IGU o CLI como texto de botones, entradas de menú o indicaciones que el lector encuentra en la pantalla de comandos o nombres de paquetes

Utilice un símbolo del sistema ($ o #) para indicar el nivel de privilegio y diferenciar la entrada diferente de la salida.

[origen,consola] ---- $ instrucción arg1 arg2 salida línea1 salida línea2 ----

Los consejos, sugerencias y advertencias, cuando se usan en exceso, interrumpen el flujo de la escritura y la lectura. Use advertencias cuando sea absolutamente necesario.

Si es posible, use una máquina virtual invitada nueva, o al menos una cuenta de usuario completamente nueva. Ejecute el proceso de principio a fin para asegurarse de que funcione. ¡Repare, reinicie y repita!

Este artículo pudo cubrir software no-FOSS para ser utilizado en Fedora, donde no hay alternativa de software FOSS para usuarios de Fedora.

A menos que su artículo de documentación apunte específicamente a un mecanismo de distribución cruzada, utilice instalaciones, contenedores o distribuciones dentro de nuestra familia (Fedora, CentOS, RHEL).

Los derechos del sistema de compilación no está gestionado por el equipo de lanzamiento de Fedora y no proporciona compilaciones oficiales de software. Si utiliza derechos de copia del software, asegúrese que no exista una compilación oficial. De lo contrario, incluya una declaración como esta: Los derechos de copia no cuentan con soporte oficial de la infraestructura de Fedora. Use los paquetes bajo su propia responsabilidad.

Estos son ejemplos de terminología que se debe evitar en los artículos:

Los nombres de empresas, proyectos y tecnologías no siempre siguen las reglas de estilo de las palabras típicas del inglés. Si tiene dudas, elija el estilo que utilizan los sitios web de confianza. Si las fuentes de confianza utilizan un estilo inconsistente, utilice su criterio. Lista no exhaustiva:

No utilice su sistema o configuración personal. Es mejor hacer una máquina virtual con una instalación variante de Fedora reciente, y realice los pasos allí.

El software de captura de pantalla específico para entornos de escritorio genera imágenes del tamaño adecuado para los artículos. Si está mostrando una ventana del navegador, utilice la opción de ventana activa en el software de captura de pantalla. Opte por no incluir la barra de título de la ventana.

Si la captura requiere una ventana completa del navegador, una aplicación a tamaño completo o pantalla completa, elija una miniatura de tamaño mediano. Use descripciones de las imágenes antes de la macro de bloque para explicar las acciones que exhibe la imagen. Consulte la página siguiente para ver el marcado de AsciiDoc.

Compruebe su trabajo antes de crear un Pull Request.

Utilice Vale para comprobar su trabajo para asegurar su conformes a la Guía de Estilo de Red Hat.