Procedimientos recomendados para documentos de GitHub

Siga estos procedimientos recomendados para crear documentación fácil de usar y de entender.

En este artículo

Acerca de la documentación de GitHub

En GitHub nos esforzamos por crear documentación precisa, valiosa, inclusiva, accesible y fácil de usar.

Antes de contribuir a GitHub Docs, dedica un momento a familiarizarte con la filosofía de la documentación, los aspectos básicos y los principios de diseño de contenido de GitHub:

  •         [AUTOTITLE](/contributing/writing-for-github-docs/about-githubs-documentation-philosophy)

  •         [AUTOTITLE](/contributing/writing-for-github-docs/about-githubs-documentation-fundamentals)

  •         [AUTOTITLE](/contributing/writing-for-github-docs/content-design-principles)

Procedimientos recomendados para escribir documentación de GitHub

Independientemente de si va a crear un nuevo artículo o actualizar uno existente, debe seguir estas instrucciones al escribir para GitHub Docs:

  •         [Alineación del contenido con las necesidades del usuario](#align-content-to-user-needs)

  •         [Estructuración del contenido para que sea legible](#structure-content-for-readability)

  •         [Escritura para que sea legible](#write-for-readability)

  •         [Formatear para que sea escaneable](#format-for-scannability)

Alineación del contenido con las necesidades del usuario

Antes de empezar, es importante comprender para quién está escribiendo, cuáles son sus objetivos, las tareas o conceptos básicos que abordará el artículo y qué tipo de contenido escribir.

Definición del público

  • ¿Quién leerá este contenido?
  • ¿Qué está intentando hacer?

Definición del propósito principal

  • ¿Qué debe ser capaz de hacer o entender alguien después de leer este artículo? Elija una o dos tareas o conceptos que analizará el contenido.
  • Si hay tareas, conceptos o información adicionales que no son esenciales, considere si se pueden colocar más abajo en el artículo, moverse a otro artículo u omitirse por completo.

Determinación del tipo de contenido

Determine qué tipo de contenido escribirá, en función del público objetivo y del propósito principal del contenido. GitHub Docs utilizan los siguientes tipos de contenido:

  •         [Contenido conceptual](/contributing/style-guide-and-content-model/conceptual-content-type)

  •         [Contenido referencial](/contributing/style-guide-and-content-model/referential-content-type)

  •         [Contenido de procedimientos](/contributing/style-guide-and-content-model/procedural-content-type)

  •         [Contenido de solución de problemas](/contributing/style-guide-and-content-model/troubleshooting-content-type)

  •         [Guía de inicio rápido](/contributing/style-guide-and-content-model/quickstart-content-type)

  •         [Tutorial](/contributing/style-guide-and-content-model/tutorial-content-type)

Por ejemplo, use el tipo de contenido conceptual para ayudar a los lectores a comprender los conceptos básicos de una característica o un tema y cómo puede ayudarles a lograr sus objetivos. Use el tipo de contenido de procedimientos para ayudar a los usuarios a completar una tarea específica de principio a fin.

Estructuración del contenido para que sea legible

Use los siguientes procedimientos recomendados para estructurar el contenido. Al agregar contenido a un artículo existente, siga la estructura existente siempre que sea posible.

  •         **Proporcione el contexto inicial**. Defina el tema e indique su relevancia para el lector.

  •         **Estructure el contenido en un orden lógico**, por importancia y relevancia. Coloque la información en orden de prioridad y, en el orden en que los usuarios lo necesitarán.

  •         **Evite frases y párrafos largos**.
    • Introduzca los conceptos uno por uno.
    • Use una idea por párrafo.
    • Use una idea por frase.
  •         **Enfatice la información más importante**.
    • Comience cada frase o párrafo con las palabras y las conclusiones más importantes.
    • Al explicar un concepto, comience por la conclusión y después explíquelo con más detalle. (Esto a veces se denomina "pirámide invertida").
    • Al explicar un tema complejo, presente primero a los lectores la información básica y explique los detalles más adelante.
  •         **Use subtítulos significativos**. Organice los párrafos relacionados en secciones. Asigne a cada sección un subtítulo único y que describa con precisión el contenido.

  •         **Considere la posibilidad de usar vínculos de página** para contenido más largo. Esto permite a los lectores saltar a áreas de interés y omitir contenido que sea irrelevante para ellos.

Escritura para que sea legible

Facilite la lectura y comprensión del texto a los usuarios ocupados.

  •         **Use lenguaje claro.** Use palabras comunes, cotidianas y evite el argot siempre que sea posible. Los términos que son bien conocidos por los desarrolladores pueden usarse, pero no suponga que el lector conoce los detalles de cómo funciona GitHub.

  •         **Uso de la voz activa.**

  •         **Sea conciso.**
    • Escriba oraciones sencillas y breves.
    • Evite frases complejas que contengan varios conceptos.
    • Elimine los detalles innecesarios.

Para obtener información relacionada, vea "Voz y tono" en Guía de estilo y Redacción de contenido para traducir.

Formatear para que sea escaneable

La mayoría de los lectores no consumen artículos en su totalidad. En vez de eso, escanean la página para buscar información específica o leen por encima la página para hacerse con una idea general de los conceptos.

Al escanear o leer por encima el contenido, los lectores omiten importantes fragmentos de texto. Buscan elementos relacionados con su tarea o que destacan en la página, como encabezados, alertas, listas, tablas, bloques de código, objetos visuales y las primeras palabras de cada sección.

Una vez que el artículo cuenta con un propósito y una estructura claramente definidos, podrá aplicar las siguientes técnicas de formato de texto para optimizar el contenido para el escaneo y la lectura rápida. Estas técnicas también pueden ayudar a que el contenido sea más comprensible para todos los lectores.

  •         **Use resaltado de texto**, como negrita e hipervínculos para llamar la atención sobre los puntos más importantes. Use el subrayado con moderación. No subraye más del 10 % del texto total de un artículo.

  •         **Use elementos de formato** para separar el contenido y crear espacio en la página. Por ejemplo:
    • Listas con viñetas (con subtítulos opcionales integrados)
    • Listas numeradas
    •       [Alertas](/contributing/style-guide-and-content-model/style-guide#alerts)
    • Tablas
    • Elementos visuales
    • Bloques de código y anotaciones de código

Información adicional

  •         [AUTOTITLE](/contributing/style-guide-and-content-model/style-guide)

  •         [AUTOTITLE](/contributing/style-guide-and-content-model/about-the-content-model)

  •         [AUTOTITLE](/contributing/style-guide-and-content-model/contents-of-a-github-docs-article)

  •         [Directrices de legibilidad](https://readabilityguidelines.co.uk/), Content Design London

  •         [Reescritura de contenido digital para que sea breve](https://www.nngroup.com/articles/rewriting-content-brevity/), Nielsen Norman Group