Directrices de documentación

Esta página describe las reglas que debes seguir si deseas contribuir a Godot Engine escribiendo o revisando documentación, o si deseas traducir documentación existente. También, echa un vistazo al archivo README del repositorio de GitHub godot-docs y a la página principal de la documentación docs para conocer los pasos a seguir y cómo ponerte en contacto con el equipo de documentación.

Como contribuir

La creación o modificación de páginas de documentación se realiza principalmente a través del repositorio de GitHub godot-docs. La documentación en formato HTML (o PDF y EPUB) se genera a partir de los archivos .rst (lenguaje de marcado reStructuredText) en ese repositorio. Al modificar esas páginas en una solicitud de extracción (pull request) y obtener que sea fusionada, se activará una reconstrucción de la documentación en línea.

Ver también

Para obtener detalles sobre el uso de Git y el flujo de trabajo de solicitudes de extracción (pull requests), consulta la página Flujo de trabajo para los Pull request. La mayoría de lo que describe sobre el repositorio principal godotengine/godot también es válido para el repositorio de documentación.

Advertencia

The class reference's source files are in the Godot engine repository. We generate the Godot API section of this documentation from them. If you want to update the description of a class, its methods, or properties, read Contribuyendo a la referencia de la clase.

Advertencia

Si deseas editar la referencia de la API, ten en cuenta que no debes hacerlo en el repositorio godot-docs. En su lugar, debes editar los archivos XML en la carpeta doc/classes/* del repositorio principal de Godot. Estos archivos se utilizan posteriormente para generar la documentación en el editor y la referencia de la API en la documentación en línea. Lee más aquí: Contribuyendo a la referencia de la clase.

El link 'Editar en GitHub'

Si estás leyendo la documentación en docs.godotengine.org, verás un enlace Editar en GitHub en la parte superior derecha de la página. Una vez que hayas creado una cuenta en GitHub, puedes proponer cambios a una página que estás leyendo de la siguiente manera:

1. Haz clic en el botón "Editar en GitHub".

2. En la página de GitHub a la que te diriges, haz clic en el ícono del lápiz que se encuentra en la esquina superior derecha, cerca de los botones Raw, Blame e History. Tiene el texto emergente "Editar el archivo en un fork de este proyecto".

3. Completa todas las ediciones que desees realizar en esa página.

4. Resume los cambios que realizaste en el formulario en la parte inferior de la página y haz clic en el botón etiquetado Propose file change cuando hayas terminado.

5. En las siguientes pantallas, haz clic en el botón Create pull request hasta que veas un mensaje como Username quiere fusionar 1 confirmación en godotengine:master desde Username:patch-6.

6. Un revisor evaluará tus cambios y los incorporará en la documentación si son aceptables. Es posible que también te pidan hacer modificaciones a tus cambios antes de incluirlos.

¿Qué hace buena una documentación?

La documentación debe estar bien escrita en inglés sencillo, utilizando oraciones bien estructuradas y diferentes niveles de secciones y subsecciones. Debe ser clara y objetiva. También, echa un vistazo a las directrices de escritura de documentación.

Diferenciamos las páginas de tutoriales de otras páginas de documentación mediante las siguientes definiciones:

• Tutorial: una página con el objetivo de explicar cómo utilizar uno o varios conceptos en el editor o en scripts para lograr un objetivo específico con fines de aprendizaje (por ejemplo: "Crear un sencillo juego de Pong en 2D", "Aplicar fuerzas a un objeto").

• Documentación: una página que describe precisamente un único concepto a la vez, si es posible de manera exhaustiva (por ejemplo: la lista de métodos de la clase Sprite, o una descripción general de la gestión de entrada en Godot).

Eres libre de escribir el tipo de documentación que desees, siempre y cuando respetes las siguientes reglas (y las que se encuentran en el repositorio).

Títulos

Siempre comienza las páginas con su título y un nombre de referencia de Sphinx:

.. _doc_insert_your_title_here:

Insert your title here
======================

La referencia permite vincular a esta página utilizando el formato :ref:, por ejemplo, :ref:`doc_insert_your_title_here` enlazaría a la página de ejemplo anterior (nota la falta de guión bajo al principio de la referencia).

Además, evita los títulos en estilo CamelCase americano: la primera palabra del título debe comenzar con una letra mayúscula, y cada palabra siguiente no debe estar en mayúscula. Por lo tanto, este es un buen ejemplo:

• Inserte su titulo aqui

Y este es un mal ejemplo:

• Inserte Su Titulo Aqui

Solo los nombres de proyectos, personas y clases de nodos deben tener la primera letra en mayúscula.

Traduciendo paginas existentes

Puedes ayudar a traducir la documentación oficial de Godot en nuestro Hosted Weblate.

También está el repositorio oficial Godot i18n donde puedes ver cuándo se sincronizó por última vez la información.

Licencia

Esta documentación y todas las páginas que contiene están publicadas bajo los términos de la licencia Creative Commons Attribution 3.0 (CC-BY 3.0), con atribución a "Juan Linietsky, Ariel Manzur y la comunidad Godot".

Al contribuir a la documentación en el repositorio de GitHub, aceptas que tus cambios se distribuyen bajo esta licencia.