Importante

La traducción es un esfuerzo comunitario puede unirse. Esta página está actualmente traducida en |progreso de traducción|.

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

Para añadir materiales a este curso, debe seguir las directrices de este Apéndice. No está permitido alterar las condiciones de este Apéndice, salvo para clarificarlas. Con ello se pretende garantizar la calidad y coherencia de este manual.

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, un generador de documentos Python que utiliza el lenguaje de marcas reStructuredText . Las instrucciones sobre como usar estas herramientas están disponibles en sus respectivos sitios.

19.3. Adición de un Módulo

Para añadir un nuevo módulo:

  1. Primero cree un nuevo directorio (directamente bajo el nivel superior del directorio qgis-training-manual) con el nombre del nuevo módulo.

  2. En este nuevo directorio, crea un fichero llamado index.rst. Deje este archivo en blanco por ahora.

  3. Abra el archivo index.rst en el directorio de nivel superior. Sus primeras líneas son:

    .. toctree::
   :maxdepth: 2

   foreword/index
   introduction/index

Observará que se trata de una lista de nombres de directorios, seguida del nombre index. Esto dirige el archivo de índice de nivel superior a los archivos de índice de cada directorio. El orden en que se enumeran determina el orden que tendrán en el documento.

  1. Añada el nombre de tu nuevo módulo (es decir, el nombre que le has dado al nuevo directorio), seguido de /index, a esta lista, donde quieras que aparezca tu módulo.

  2. 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.

  3. Abra el archivo de índice de su nuevo módulo (module_name/index.rst).

  4. En la parte superior de la página, cree el encabezamiento del módulo:

    1. escribir una primera línea de asteriscos (*).

    2. Siga esto con una línea que contenga la frase de marcado Módulo:, seguida del nombre de su módulo.

    3. Termine esto con otra línea del mismo número de asteriscos.

    Nota

    El subrayado y el sobretitulado no deben ser más cortos que la línea que contiene el título del módulo.

  5. Deja una línea abierta por debajo.

  6. Escribe un párrafo corto explicando el propósito y contenido del módulo.

  7. Deja una línea abierta, luego añade el texto siguiente:

    .. toctree::
   :maxdepth: 2

   lesson1
   lesson2

    … donde lección1, lección2, etc., son los nombres de las lecciones planificadas.

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

*******************************************************************************
Module: 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:

  1. Abre el directorio del módulo.

  2. Abra el archivo index.rst (creado anteriormente en el caso de módulos nuevos).

  3. Asegúrese de que el nombre de la lección planificada aparece debajo de la directiva toctree, como se muestra arriba.

  4. Crea un archivo nuevo en el directorio del módulo.

  5. Asigne a este archivo el mismo nombre que al archivo index.rst del módulo y añádale la extensión .rst.

Nota

A efectos de edición, un archivo .rst funciona exactamente igual que un archivo de texto normal (.txt).

  1. Para empezar a escribir la lección, escriba la frase de marcado Lección, seguida del nombre de la lección.

  2. En la línea siguiente, escriba una línea de signos iguales (=), no más corta que el título de la lección.

  3. Deja una línea abierta después de eso.

  4. Escribe una corta descripción del propósito de la lección.

  5. Incluye una introducción general del tema. Mira lecciones existentes como ejemplos.

  6. Debajo, comienza un nuevo párrafo, comenzando con esta frase:

    **The goal for this lesson:**

  7. Explica brevemente el resultado previsto a completar en esta lección.

  8. 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 «Inténtalo tú mismo» ofrece al lector una breve tarea que puede intentar por sí mismo. Suele ir asociada a una entrada en el cuadro de respuestas situado debajo, que mostrará o explicará cómo completar la tarea y, si es posible, mostrará el resultado esperado.

Cada sección tiene un nivel de dificultad. Una sección fácil se indica con ★☆☆, moderada con ★★☆ y avanzada con ★★★.

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

  1. Para comenzar esta lección, escribe la frase de marcado de la dificultad del nivel (como se muestra arriba).

  2. Deje un espacio y escriba Seguir:.

  3. 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).

  4. En la línea siguiente, escriba una línea de menos/guiones (-), no más corta que el título de la sección.

  5. Escribe una introducción corta a la sección, explicando sus objetivos. Luego dá instrucciones detalladas (clic por clic) al procedimiento a ser demostrado.

  6. En cada sección, incluye enlaces internos y externos y capturas de pantalla según se necesiten.

  7. 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»

  1. Para comenzar esta lección, escribe la frase de marcado de la dificultad del nivel (como se muestra arriba).

  2. Deje un espacio y escriba Pruébese:.

  3. En la línea siguiente, escriba una línea de menos/guiones (-), no más corta que el título de la sección.

  4. Explica el ejercicio que quieres que el lector complete. Refiérete a las secciones, lecciones o módulos anteriores si es necesario.

  5. Incluye capturas de pantalla para clarificar los requisitos si alguna descripción textual no está clara.

En la mayoría de los casos, querrá dar una respuesta sobre cómo completar la tarea dada en esta sección. Para ello, deberá crear y alimentar un bloque de respuesta debajo de las instrucciones.

  1. En primer lugar, cree el widget plegable personalizado que contiene la respuesta:

    .. admonition:: Answer
   :class: dropdown

  2. Manteniendo una sangría con respecto al bloque anterior, escriba las instrucciones sobre cómo completar la tarea, utilizando enlaces e imágenes cuando sea necesario.

19.6. Añadir una Conclusión

Para terminar una lección:

  1. Escriba la frase En conclusión, seguida de una nueva línea de menos/guiones (-).

  2. Escribe una conclusión para la lección, explicando qué conceptos se han tratado en la lección.

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

Esta sección es opcional.

  • Escriba la frase Lectura adicional, seguida de una nueva línea de menos/guiones (-).

  • Incluye enlaces a webs externas apropiadas.

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

  1. Escribe la frase ¿Qué sigue?, seguida de una nueva línea de menos/guiones (-).

  2. Explica cómo esta lección ha preparado a los estudiantes para las secciones o módulos siguientes.

  3. 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á explicando un nuevo concepto, deberá escribir el nombre del nuevo concepto en cursiva encerrándolo entre asteriscos (*).

This sample text shows how to introduce a *new concept*.

19.9.2. Énfasis

  • Para destacar un término crucial que no sea un concepto nuevo, escríbalo en negrita encerrándolo entre dos 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ñada una imagen, guárdela en una carpeta img junto al archivo de la lección.

  • 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.6. Utilizar el texto monoespaciado

  • Cuando escriba un texto que el usuario deba introducir, un nombre de ruta o el nombre de un elemento de la base de datos, como el nombre de una tabla o columna, debe escribirlo en texto monoespaciado. Por ejemplo:

    Enter the following path in the text box: ``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

  • Es posible que tenga que añadir una nota en el texto, que explique detalles adicionales que no se pueden incluir fácilmente en el flujo de la lección. Este es el marcado:

    [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 se ha ofrecido voluntario para escribir un módulo, lección o sección a título personal, y no en nombre de un patrocinador, puede incluir una nota de autoría debajo del título del módulo, lección o sección de su autoría. Esta nota debe ser del tipo «Este [módulo/lección/sección] ha sido escrito por [nombre del autor]». Estos datos deben añadirse en la sección «Colaboradores» del Prólogo, junto con el nombre de la(s) parte(s) que ha añadido. Si sólo ha realizado mejoras, correcciones y/o añadidos, indíquese 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.