Directrices de contenido

Este documento está aquí para ayudarnos a evaluar qué debemos incluir en la documentación oficial. A continuación, encontrarás algunos principios y recomendaciones para escribir contenido accesible.

Nosotros queremos alcanzar dos metas:

1. Empatiza con nuestros usuarios. Debemos escribir de una manera que les facilite aprender de la documentación.

2. Escribe un manual de referencia completo. Nuestro objetivo aquí no es enseñar fundamentos de programación. En su lugar, debemos proporcionar una referencia sobre cómo funcionan las características de Godot.

Directrices y principios

A continuación se presentan las directrices que debemos esforzarnos por seguir. No son reglas estrictas, sin embargo, en casos excepcionales, un tema podría requerir romper una o más de ellas. Aun así, debemos esforzarnos por alcanzar los dos objetivos mencionados anteriormente.

Escribir documentación completa y accesible

Una característica no existe a menos que esté documentada. Si un usuario no puede encontrar información sobre una característica y cómo funciona, para ellos esa característica no existe. Debemos asegurarnos de cubrir todo lo que hace Godot.

Nota

Cuando se agrega o actualiza una característica del motor, el equipo de documentación necesita estar informado al respecto. Los colaboradores deben abrir un issue en el repositorio godot-docs cuando su trabajo se haya fusionado y requiera documentación.

Haz lo posible para mantener los documentos con una extensión inferior a 1000 palabras. Si una página supera ese límite, considera dividirla en dos partes si es posible. Limitar el tamaño de la página nos obliga a escribir de manera concisa y dividir documentos grandes para que cada uno se centre en un problema específico.

Asegúrate de dejar claro qué problema aborda cada página o sección de una página y qué aprenderá el usuario de ella. Los usuarios necesitan saber si están leyendo la guía correcta para resolver los problemas que encuentran. Por ejemplo, en lugar de escribir el encabezado "Señales", considera escribir "Reaccionar a cambios con señales". El segundo título deja claro cuál es el propósito de las señales.

Nota

Los títulos de sección largos resultan en entradas largas en el menú lateral, lo que puede dificultar la navegación. Trata de mantener los encabezados con un máximo de cinco palabras o menos.

Si una página asume un conocimiento específico de otras características de Godot, mencionarlo y enlazarlo con la documentación correspondiente. Por ejemplo, una página sobre física puede utilizar señales, en cuyo caso podríamos mencionar que la página que presenta las señales es un prerequisito.

Limitar la carga cognitiva

Limitar la carga cognitiva requerida para leer la documentación. Cuanto más simple y explícito sea el lenguaje que utilizamos, más eficiente será para que las personas aprendan. Puedes lograrlo mediante:

1. Introducir solo un nuevo concepto a la vez siempre que sea posible.

2. Usar un inglés simple, como recomendamos en nuestras pautas de escritura.

3. Incluir uno o más ejemplos de uso concretos. Prefiere un ejemplo del mundo real en lugar de código abstracto como foobar.

Si bien muchas personas pueden entender un lenguaje más complejo y ejemplos abstractos, también se perderá a otras. Escribir de forma comprensible y proporcionar ejemplos prácticos beneficia a todos.

Siempre haz un esfuerzo por ponerte en el lugar del usuario. Cuando entendemos algo completamente, nos resulta evidente. Podemos olvidar pensar en detalles relevantes para un recién llegado, pero una buena documentación llega a los usuarios donde están. Debemos esforzarnos por explicar las capacidades o usos previstos de cada característica con el lenguaje más sencillo posible.

Trata de recordar lo que necesitaste saber cuando aprendías sobre la característica o el concepto por primera vez. ¿Qué términos nuevos necesitaste aprender? ¿Qué te confundió? ¿Qué fue lo más difícil de comprender? Querrás que los usuarios revisen tu trabajo, y te recomendamos practicar explicar la característica antes de escribir sobre ella.

Nota

Tener bases de programación es un requisito previo para usar un motor complejo como Godot. Hablar de variables, funciones o clases es aceptable. Pero debemos preferir un lenguaje sencillo en lugar de terminología específica como "metaprogramación". Si es necesario utilizar términos precisos, asegúrate de definirlos.

Cuando una página asume el conocimiento de otra característica del motor, decláralo al principio y enlaza a recursos que cubran lo que los usuarios necesitan. También puedes enlazar a otros sitios web para requisitos previos más allá del alcance de la documentación. Por ejemplo, podrías enlazar a una introducción a la programación en la guía de inicio, o a un sitio web que enseñe teoría matemática en la sección de matemáticas.