Importante

Translation is a community effort you can join. This page is currently translated at 60.19%.

19. Apêndice: Contribuindo para este manual

To add materials to this course, you must follow the guidelines in this Appendix. You are not allowed to alter the conditions in this Appendix except for clarification. This is to ensure that the quality and consistency of this manual can be maintained.

19.1. Download de recursos

A fonte deste documento está disponível em ‘GitHub <https://github.com/qgis/QGIS-Documentation>’_. Consulte ‘GitHub.com <https://github.com/>’_ para obter instruções sobre como usar o sistema de controle de versão git.

19.2. Formato do Manual

This manual is written using Sphinx, a Python document generator using the reStructuredText markup language. Instructions on how to use these tools are available on their respective sites.

19.3. Adicionando um módulo

To add a new module:

1. First create a new directory (directly under the top-level of the qgis-training-manual directory) with the name of the new module.

2. Under this new directory, create a file called index.rst. Leave this file blank for now.

3. Open the index.rst file under the top-level directory. Its first lines are:

   .. toctree::
      :maxdepth: 2
   
      foreword/index
      introduction/index
   

You will note that this is a list of directory names, followed by the name index. This directs the top-level index file to the index files in each directory. The order in which they are listed determines the order they will have in the document.

1. Add the name of your new module (i.e., the name you gave the new directory), followed by /index, to this list, wherever you want your module to appear.

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. Open your new module’s own index file (module_name/index.rst).

4. Along the top of the page, create the module heading:

   1. write a first line of asterisks (*).

   2. Follow this with a line containing the markup phrase Module:, followed by the name of your module.

   3. End this off with another line of same number of asterisks.

   Nota

   The underline and the overline should not be shorter than the line containing the module title.

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
   

   … where lesson1, lesson2, etc., are the names of your planned lessons.

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. Open the index.rst file (created above in the case of new modules).

3. Ensure that the name of the planned lesson is listed underneath the toctree directive, as shown above.

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

5. Name this file exactly the same as the name you provided in the module’s index.rst file, and add the extension .rst.

Nota

For editing purposes, a .rst file works exactly like a normal text file (.txt).

1. To begin writing the lesson, write the markup phrase Lesson, followed by the lesson name.

2. In the next line, write a line of equal signs (=), not shorter than the lesson title.

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.

• A “try yourself” section gives the reader a short assignment to try by themselves. It is usually associated with an entry in the answer box beneath, which will show or explain how to complete the assignment, and will show the expected outcome if possible.

Every section comes with a difficulty level. An easy section is denoted by ★☆☆, moderate by ★★☆, and advanced by ★★★.

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. Leave a space and then write Follow Along:.

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. In the next line, write a line of minuses/dashes (-), not shorter than the section title.

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. Leave a space and then write Try Yourself:.

3. In the next line, write a line of minuses/dashes (-), not shorter than the section title.

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.

In most cases, you will want to provide an answer regarding how to complete the assignment given in this section. To do so, you will need to create and feed an answer block beneath the instructions.

1. First, create the custom collapsible widget that contains the answer:

   .. admonition:: Answer
      :class: dropdown
   

2. Keeping an indentation with regard to the above block, write the instructions on how to complete the assignment, using links and images where needed.

19.6. Añadir una Conclusión

To end a lesson:

1. Write the phrase In Conclusion, followed by a new line of minuses/dashes (-).

2. Write a conclusion for the lesson, explaining which concepts have been covered in the lesson.

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

Esta sección es opcional.

• Write the phrase Further Reading, followed by a new line of minuses/dashes (-).

• Incluye enlaces a webs externas apropiadas.

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

1. Write the phrase What's Next?, followed by a new line of minuses/dashes (-).

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

If you are explaining a new concept, you will need to write the new concept’s name in italics by enclosing it in asterisks (*).

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

19.9.2. Énfasis

• To emphasize a crucial term which is not a new concept, write the term in bold by enclosing it in double asterisks (**).

• ¡Ú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

• When adding an image, save it to an img folder next to the lesson file.

• 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:
  

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

• To create a link, refer to it as below:

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

19.9.5. Enlaces externos

• Para crear un enlace externo, escribelo así:

  `Descriptive link text <link-url>`_
  

19.9.6. Utilizar el texto monoespaciado

• When you are writing text that the user needs to enter, a path name, or the name of a database element such as a table or column name, you must write it in monospaced text. For example:

  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.8. Selecciones del menú

• Si estás guiando al usuario a través de los menús, debes utilizar el menú ► selección ► formato. Por ejemplo:

  To use the :guilabel:`Tool Name` tool, go to :menuselection:`Plugins -->
  Tool Type --> Tool Name`.
  

19.9.9. Añadir notas

• You might need to add a note in the text, which explains extra details that can’t easily be made part of the flow of the lesson. This is the markup:

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

If you have volunteered to write a module, lesson or section in your own capacity, and not on behalf of a sponsor, you may include an authorship note below the heading of the module, lesson or section that you authored. This must take the form This [module/lesson/section] contributed by [author name]. Do not add further text, contact details, etc. Such details are to be added in the “Contributors” section of the Foreword, along with the name(s) of the part(s) you added. If you only made enhancements, corrections and/or additions, list yourself as an 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.