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:

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

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 usan los siguientes tipos de contenido:

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 para los desarrolladores pueden usarse, pero 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 Escritura de contenido que se va a 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 tiene un propósito y una estructura claramente definidos, puede aplicar las siguientes técnicas de formato para optimizar el contenido para que pueda ser escaneado y leído por encima. 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)
    • Listas numeradas
    • Alertas
    • Tablas
    • Objetos visuales
    • Bloques de código y anotaciones de código

Información adicional