19. Apéndice: Cómo Contribuir a este Manual

Para añadir materiales a este curso, debes seguir las guías de este Apéndice. No debes alterar las condiciones de este Apéndice salvo para clarificaciones. Todo esto es para asegurar que la calidad y consistencia del manual se mantiene.

19.1. Descarga de Recursos

Los recursos de este documento están disponibles en GitHub. Consulta en GitHub.com para obtener instrucciones sobre cómo utilizar el sistema de control de versiones git.

19.2. Formato del Manual

Este manual está escrito usando Sphinx <https://www.sphinx-doc.org/en/master/> _, un generador de documentos de Python que usa el lenguaje con etiquetas `reStructuredText <http://docutils.sourceforge.net/rst.html > `_. Las instrucciones sobre cómo usar estas herramientas están disponibles en sus respectivos sitios.

19.3. Adición de un Módulo

Para añadir un módulo nuevo, primero crea un directorio nuevo (directamente en el nivel superior del directorio qgis-training-manual) con el nombre del módulo nuevo.
En el nuevo directorio, crea un archivo llamado index.rst. Deja el archivo en blanco de momento.

Abre el archivo index.rst en el nivel superior del directorio. Sus primeras líneas son:

.. toctree::
   :maxdepth: 2


   foreword/index
   introduction/index

Observarás que es una lista de directorios, seguido del nombre index. Esto dirige el nivel superior del archivo índice a cada directorio. El orden en el que están listados determina el orden que tendrán en el documento.

Añade el nombre de tu nuevo módulo (es decir, el nombre que le has dado al nuevo directorio), seguido de /index, a esa lista, donde quieras que aparezca tu módulo.
Recuerda mantener el orden de los módulos de forma lógica, de forma que los módulos finales se basen en el conocimiento presentado por los iniciales.
Abre el archivo índice de tu propio módulo ([module name]/index.rst).
En la parte superior de la página, escribe una línea de 80 asteriscos (*). Esto representa un encabezado de módulo.
Síguelo con una línea conteniendo la frase marcada |MOD| (que significa «módulo»), seguido del nombre de tu módulo.
Termínalo con otra línea de 80 asteriscos.
Deja una línea abierta por debajo.
Escribe un párrafo corto explicando el propósito y contenido del módulo.
Deja una línea abierta, luego añade el texto siguiente:
```
.. toctree::
   :maxdepth: 2


   lesson1
   lesson2
```
… donde lesson1, lesson2, etc., son los nombres de tus lecciones planeadas.

El archivo índice del nivel del módulo tendrá este aspecto:

*******************************************************************************
|MOD| Module Name
*******************************************************************************

Short paragraph describing the module.

.. toctree::
   :maxdepth: 2


   lesson1
   lesson2

19.4. Adición de una Lección

Para añadir una lección a un módulo existente:

Abre el directorio del módulo.
Abre el archivo index.rst (creado antes en el caso de módulos nuevos).
Asegúrate de que el nombre de la lección planeada está listada bajo la directriz toctree, como se muestra arriba.
Crea un archivo nuevo en el directorio del módulo.
Nombra ese archivo exactamente igual al nombre del archivo index.rst del módulo, y añade la extensión .rst.

Nota

Para propósitos de edición, un archivo .rst funciona exactamente igual a un archivo de texto (.txt).

Para empezar a escribir la lección, escribe la frase |LS|, seguido del nombre de la lección.
En la siguiente línea, escribe una línea de 80 signos de igual (=).
Deja una línea abierta después de eso.
Escribe una corta descripción del propósito de la lección.
Incluye una introducción general del tema. Mira lecciones existentes como ejemplos.
Debajo, comienza un nuevo párrafo, comenzando con esta frase:
```
**The goal for this lesson:**
```
Explica brevemente el resultado previsto a completar en esta lección.
Si no puedes describir el objetivo de la lección en una o dos frases, considera dividir el tema en varias lecciones.

Cada lección estará subdividida en varias secciones, que se abordarán luego.

19.5. Añadir una Lección

Hay dos tipos de secciones: «sigue los pasos» y «prueba tú mismo».

Una sección «sigue los pasos» detalla un conjunto de direcciones para enseñar al lector cómo utilizar un aspecto dado del QGIS. Esto se hace dando direcciones clic por clic tan claramente como sea posible, intercaladas con capturas de pantalla.
La sección «prueba tú mismo» le da al lector un ejercicio corto para ponerse a prueba. Se asocia normalmente con una hoja de respuestas al final de la documentación, que demuestra o explica cómo completar el ejercicio, y mostrará los resultados esperados si es posible.

19.5.1. Añadir una sección «sique los pasos»

Para comenzar esta lección, escribe la frase de marcado de la dificultad del nivel (como se muestra arriba).
Deja un espacio y escribe |FA| (para «sigue los pasos»).
Deja otro espacio y escribe el nombre de la lección (utiliza solo una inicial en mayúsculas, así como las mayúsculas para nombres propios).
En la línea siguiente, escribe una línea de 80 menos/guiones (-). Asegúrate de que tu editor de textos no reemplaza los carácteres menos/guiones a guión largo o otro carácter por defecto.
Escribe una introducción corta a la sección, explicando sus objetivos. Luego dá instrucciones detalladas (clic por clic) al procedimiento a ser demostrado.
En cada sección, incluye enlaces internos y externos y capturas de pantalla según se necesiten.
Intenta acabar cada sección con un párrafo corto que concluya y abra paso a la siguiente sección de forma natural, si es posible.

19.5.2. Añadir una sección «prueba tú mismo»

Para comenzar esta lección, escribe la frase de marcado de la dificultad del nivel (como se muestra arriba).
Deja un espacio y escribe |TY| (para «prueba tú mismo»).
En la línea siguiente, escribe una línea de 80 menos/guiones (-). Asegúrate de que tu editor de textos no reemplaza los carácteres menos/guiones a guión largo o otro carácter por defecto.
Explica el ejercicio que quieres que el lector complete. Refiérete a las secciones, lecciones o módulos anteriores si es necesario.
Incluye capturas de pantalla para clarificar los requisitos si alguna descripción textual no está clara.

En la mayoría de los casos, querrás dar una respuesta a cómo completar el ejercicio dado en la lección. Para hacerlo, necesitarás añadir una entrada en la hoja de respuestas.

Primero, decide un único nombre para la respuesta. Idealmente, el nombre incluirá el nombre de la lección y un número que vaya incrementando.

Crea un enlace para la respuesta:

:ref:`Check your results <answer-name>`

Abre la hoja de respuestas (answers/answers.rst).
Crea un enlace para la sección «prueba tú mismo» escribiendo esta línea:
```
.. _answer-name:
```
Escribe las instrucciones sobre cómo completar el ejercicio, utilizando enlaces e imágenes donde lo necesites.
Para acabar, inluye un enlace de vuelta a la sección «prueba tú mismo» escribiendo esta línea:
```
:ref:`Back to text <backlink-answer-name>`
```
Para hacer que esta línea funcione, añade la siguiente linea encima del titulo de la sección «prueba tú mismo»:
```
.. _backlink-answer-name:
```

Recuerda que cada una de esas líneas mostradas arriba deben tener una línea en blanco sobre y bajo ellas, de otra forma se podría causar errores en la creación del documento.

19.6. Añadir una Conclusión

Para terminar una lección, escribe la frase |IC| para «en conclusión», seguida de una línea nueva de 80 menos/guiones (-). Escribe una conclusión para la lección, explicando qué conceptos ha cubierto la lección.

19.7. Añadir una Sección de Lectura Adicional

Esta sección es opcional.
Escribe la frase FR para «lectura adicional», seguido por una línea nueva de 80 menos/guiones (-).
Incluye enlaces a webs externas apropiadas.

19.8. Añade un Cuál es la Próxima Sección

Escribe la frase |WN| para «qué es lo siguiente», seguido por una línea nueva de 80 menos/guines (-).
Explica cómo esta lección ha preparado a los estudiantes para las secciones o módulos siguientes.
Recuerda cambiar la sección «qué es lo siguiente» de la lección anterior si es necesario, para que se refiera a tu nueva lección. Esto será necesario si has insertado una lección entre lecciones existentes, o después de una lección existente.

19.9. Utilizar el Marcado

Para acoplarte a los estándares de este documento, necesitarás añadir marcadores estándares a tu texto.

19.9.1. Nuevos conceptos

Si estás explicando un nuevo concepto, necesitaras escribir el nombre del nuevo concepto en itálicas escribiéndolo entre asteriscos (*).
```
This sample text shows how to introduce a *new concept*.
```

19.9.2. Énfasis

Para enfatizar un término crucial que no es un concepto nuevo, escribe el término en negrita escribiendolo entre dobles asteriscos (**).
¡Úsalo moderadamente! Si lo usas demasiado, puede parecer que estás gritando o siendo condescendiente.

This sample text shows how to use **emphasis** in a sentence. Include the
punctuation mark if it is followed by a **comma,** or at the **end of the
sentence.**

19.9.3. Imágenes

Cuando añades una imagen, guárdala a la carpeta _static/lesson_name/.

Inclúyela en el documento de esta forma:

.. figure:: img/image_file.extension
   :align: center

Recuerda dejar una línea abierta sobre y bajo el marcador de la imagen.

19.9.4. Enlaces internos

Para anclar un enlace, escribe la línea siguiente sobre la posición donde quieras que el enlace señale:
```
.. _link-name:
```

Para crear un enlace, añade esta línea:

:ref:`Descriptive link text <link-name>`

Recuerda dejar una línea abierta sobre y bajo esta línea.

19.9.5. Enlaces externos

Para crear un enlace externo, escribelo así:
```
`Descriptive link text <link-url>`_
```
Recuerda dejar una línea abierta sobre y bajo esta línea.

19.9.6. Utilizar el texto monoespaciado

Cuando estás escribiendo texto que el usuario tiene que introducir, un nombre de ruta, o el nombre del elemento de un conjunto de datos como una tabla o nombre de una columna, debes escribirlo en texto monoespaciado. por ejemplo:
```
Enter the following path in the text box: :kbd:`path/to/file`.
```

19.9.7. Etiquetado de elementos GUI

Si te refieres a un elemento GUI, como un botón, debes escribir su nombre en the GUI label format.Por ejemplo:
```
To access this tool, click on the :guilabel:`Tool Name` button.
```
Esto también se aplica si estás mencionando el nombre de una herramienta sin que requiera que el usuario haga clic en un botón.

19.9.9. Añadir notas

Puede que necesites una nota en el texto, que explique detalles extra que no se pueden añadir fácilmente al flujo de la lección. Este es el marcador:

[Normal paragraph.]

.. note:: Note text.
   New line within note.

   New paragraph within note.

[Unindented text resumes normal paragraph.]

19.9.10. Añadir una nota de patrocinio/autoría

Si estás escribiendo un módulo, lección o sección nuevos, en nombre de un patrocinador, debes incluir un mensaje corto de su elección. Éste debe notificar al lector el nombre del patrocinador y debe aparecer bajo el título del módulo, lección o sección que han patrocinado. Sin embargo, puede ser un anuncios de su empresa.

Si has escrito un módulo, lección o sección voluntariamente, sin ningún patrocinador, puedes incluir una autoría bajo el título del módulo, lección o sección que hayas creado. Esto debe tener la forma Este [módulo/lección/sección] aportado por [nombre del autor]. No añadas más texto, detalles de contacto, etc. Esos detalles se tienen que añadir a la sección «Contribuidores»del prefacio, con el nombre(s) de la parte(s) que has añadido. Si solo has hecho mejoras, correcciones y/o adiciones, alístate como editor.

19.10. ¡Gracias!

¡Gracias por tu aportación a este proyecto! Haciendolo, estás mejorando la accesibilidad del QGIS a usuarios y añades valor al proyecto QGIS en su conjunto.